Fixed generic() parser
[vip:vip.git] / doc / vip.txt
1 *vip.txt* VHDL Interface Plugin to copy and paste entities, components, etc.
2
3 VIP                                                   *VIP* *vip* *vip-plugin*
4 For Vim version 7.0 or later.
5 Last Change: nov. 19 2010
6
7 Contents:
8
9     Introduction.......................... |vip-introduction|
10     Installation.......................... |vip-installation|
11     Commands.............................. |vip-commands|
12     Usage................................. |vip-usage|
13     Formatting Blocks..................... |vip-formatting|
14     Configuration......................... |vip-configuration|
15     Download, Feedback and Contact........ |vip-contact|
16     License............................... |vip-license|
17     History............................... |vip-history|
18
19
20 ==============================================================================
21 INTRODUCTION                                                *vip-introduction*
22
23 VIP (VHDL Interface Plug-in) is a script which provides some facilities to
24 copy paste entities, components and instances of components.
25 For example you can copy the component :
26
27 >
28     component mux is   -- place the cursor on this line and enter :Viy
29       port (
30         INPUT  : in  std_logic_vector (15 downto 0);
31         SEL    : in  std_logic;
32         OUTPUT : out std_logic
33       );
34     end component mux;
35 <
36
37 and paste it as an instance :
38
39 >
40     mux_0 : mux   -- place the cursor here and enter :Vii
41       port map (
42         INPUT   => s_INPUT,
43         SEL     => s_SEL,
44         OUTPUT  => s_OUTPUT
45       );
46 <
47
48 VIP can
49
50 - copy an entity and paste it as
51  - an entity
52  - a component
53  - an instance
54
55 - copy a component and paste it as
56  - an entity
57  - a component
58  - an instance
59
60 - copy a instance and paste it as
61  - an instance (with auto-incrementation of the suffix number)
62
63 VIP tries to respect your indentation as much as possible (spaces, tabs,
64 spaces + tabs).
65 It can work with many different styles of writing entities, components
66 and instances, but not all of them. See the "Formatting Blocks" section.
67
68
69 ==============================================================================
70 INSTALLATION                                                *vip-installation*
71
72 Put the plugin/vip.vim file into your ~/.vim/plugin (or $HOME\vimfiles\plugin)
73 directory.
74 Put the doc/vip.txt into your ~/.vim/doc (or $HOME\vimfiles\doc) directory.
75
76 Run ":helptags ~/.vim/doc" (":helptags $HOME/vimfiles/doc")
77
78
79 ==============================================================================
80 COMMANDS                                                        *vip-commands*
81
82 :Viy or <leader>y copy a block (entity, component or instance of component)
83                   [Vhdl Interface Yank]
84 :Vie or <leader>e paste as entity [Vhdl Interface Entity]
85 :Vic or <leader>c paste as component [Vhdl Interface Component]
86 :Vii or <leader>i paste as instance [Vhdl Interface Instance]
87
88
89 ==============================================================================
90 USAGE                                                              *vip-usage*
91
92 To copy a block, place the cursor on the line with "entity", or "component"
93 word. For instance of components, place the cursor on the instance name.
94
95 Enter the command :Viy to copy the block.
96
97 To paste the block, place the cursor where you want to paste it and enter :
98 :Vie to paste as an entity
99 :Vic to paste as a component
100 :Vii to paste as an instance of a component
101
102 When an entity or a component is pasted as an instance, the ports are
103 duplicated as signals with a "s_" prefix added.
104 If you copy the component (or the entity) :
105
106 >
107     component mux is  -- place cursor here
108       port (
109         INPUT  : in  std_logic_vector (15 downto 0);
110         SEL    : in  std_logic;
111         OUTPUT : out std_logic
112       );
113     end component mux;
114 <
115
116 and paste it as an instance. The copy will be :
117
118 >
119     mux_0 : mux
120       port map (
121         INPUT   => s_INPUT,
122         SEL     => s_SEL,
123         OUTPUT  => s_OUTPUT
124       );
125 <
126
127 The name of the instance is a duplication of the component's name with a
128 suffix ("_0") added. The suffix number is auto-incremented when you do
129 multiple paste of the same component.
130
131 To copy an instance, place the cursor on the line with the instance name :
132
133 >
134     U2 : clock  -- place cursor here
135       generic map (g_WIDTH => 14)
136       port map (
137         DATA    => s_DATA,
138         CLK     => s_CLK,
139         RST_SRn => s_RSTn,
140         CLK     => s_CLKOUT0(0)
141       );
142 <
143
144 and use the :Viy command to copy and the :Vii to paste.
145 If the instance name has a suffix, the suffix number is incremented.
146 Otherwise, the suffix is added :
147
148 >
149     U2_0 : clock  -- place cursor here
150       generic map (g_WIDTH => 14)
151       port map (
152         DATA    => s_DATA,
153         CLK     => s_CLK,
154         RST_SRn => s_RSTn,
155         CLK     => s_CLKOUT0(0)
156       );
157 <
158
159
160 ==============================================================================
161 FORMATTING BLOCKS                                             *vip-formatting*
162
163 VIP needs some formatting to parse correctly a block. It will fail to read a
164 block if the opening brace is followed by text or if there is no "port" or
165 "generic" keyword before the opening brace on the same line.
166 Do not put a blank line inside your block. VIP stops at a blank line, this is to
167 avoid parsing the whole file if a closing brace is missing. Instead of a blank line, use a comment line.
168 Each signal shuld be on a separate line
169
170 To resume :
171   - No text after the opening brace
172   - "port" or "generic" before the opening brace, on the same line
173   - No blank line in the body of the block
174   - Each signal should be on separate line
175
176 Here is some examples of formatting which ** WILL NOT ** work with VIP :
177
178 >
179     -- Bad formatting
180     -- No "port" or "generic" before the opening brace
181     component mux is port
182     (
183       INPUT  : in  std_logic_vector (15 downto 0);
184       OUTPUT : out std_logic
185     );
186     end component mux;
187
188     -- Bad formatting
189     -- Text after the opening brace
190     component mux is
191       port  (  INPUT  : in  std_logic_vector (15 downto 0);
192         OUTPUT : out std_logic
193       );
194     end component mux;
195
196     -- Bad formatting
197     -- Comment after the opening brace
198     component mux is
199       port  (   -- bad placed comment
200         INPUT  : in  std_logic_vector (15 downto 0);
201         OUTPUT : out std_logic
202       );
203     end component mux;
204
205     -- Bad formatting
206     -- Text after the opening brace
207     U0 : clock port map ( CLK => s_CLK );
208
209     -- Bad formatting
210     -- Blank line in the component body
211     component mux is
212       port  (
213         INPUT  : in  std_logic_vector (15 downto 0);
214
215         OUTPUT : out std_logic
216       );
217     end component mux;
218
219     -- Bad formatting
220     -- Several signal on same line
221     entity dsr is
222      port (
223       D, CLK, S : in std_logic;
224       Q : out std_logic);
225     end entity dsr;
226
227 <
228
229 Here is some examples of formatting which will work with VIP :
230
231 >
232     -- Good formatting for VIP
233     component mux is port (
234       INPUT  : in  std_logic;
235       SEL    : in  std_logic;
236       OUTPUT : out std_logic
237     );
238     end component mux;
239
240     -- Good formatting for VIP
241     component mux is
242       port (
243         INPUT  : in  std_logic;
244         SEL    : in  std_logic;
245         OUTPUT : out std_logic_vector (15 downto 0)
246       );
247     end component mux;
248
249     -- Good formatting for VIP
250     component mux is
251       port (
252         INPUT  : in  std_logic;
253         SEL    : in  std_logic;
254         OUTPUT : out std_logic_vector (15 downto 0) );
255     end component mux;
256
257     -- Good formatting for VIP
258     component mux is
259       port  (
260         -- inputs
261         INPUT  : in  std_logic_vector (15 downto 0);
262         -- output
263         OUTPUT : out std_logic
264       );
265     end component mux;
266
267     -- Good formatting for VIP
268     U0 : clock port map (
269       DATA     => s_DATA,
270       CLK        => s_CLK,
271       RST_SRn    => s_RST_SRn,
272       DELAY      => s_DELAY
273     );
274
275     -- Good formatting for VIP
276     U1 : clock
277     port map (
278       DATA     => s_DATA,
279       CLK        => s_CLK,
280       RST_SRn    => s_RST_SRn,
281       DELAY      => s_DELAY
282     );
283
284     -- Good formatting for VIP
285     U3 : mux
286     generic map (g_WIDTH => 14)
287     port map (
288       DATA    => s_DATA,
289       CLK     => s_CLK,
290       RST_SRn => s_RSTn,
291       CLK     => s_CLKOUT0(0)
292     );
293
294     -- Good formatting for VIP
295     U4 : mux
296     generic map (
297       g_WIDTH => 14
298     )
299     port map (
300       DATA  => s_DATA,
301       CLK     => s_CLK,
302       RST_SRn => s_RSTn,
303       CLK => s_CLKOUT0(0)
304     );
305
306     -- Good formatting for VIP
307     U5 : mux generic map (g_WIDTH => 14)
308     port map (
309       DATA    => s_DATA,
310       CLK     => s_CLK,
311       RST_SRn => s_RSTn,
312       CLK => s_CLKOUT0(0)
313     );
314 <
315
316 ==============================================================================
317 CONFIGURATION                                              *vip-configuration*
318
319 To avoid the loading of VIP plugin, you can set the global variable
320 g:loaded_VIP to 1 in your vimrc file. >
321
322     let g:loaded_sequence = 1
323 <
324
325 To change the signal prefix, change the global variable g:sigPrefix_VIP.
326 Set it to an empty string ("") if you don't want a prefix. >
327
328     let g:sigPrefix_VIP = "sig_"
329     let g:sigPrefix_VIP = ""
330 <
331
332 To change the instance's name suffix, change the global variable
333 g:instSuffix_VIP.
334 Set it to an empty string ("") if you don't want a suffix. >
335
336     let g:instSuffix_VIP = "_"
337     let g:instSuffix_VIP = ""
338 <
339
340 To change the entity word, change the global variable g:entityWord_VIP. >
341     let g:entityWord_VIP = "Entity"
342     let g:entityWord_VIP = "ENTITY"
343
344 <
345
346 To change the component word, change the global variable g:componentWord_VIP. >
347
348     let g:componentWord_VIP = "Component"
349     let g:componentWord_VIP = "COMPONENT"
350 <
351
352 To disable the auto-incrementation of the instance's name, set the global
353 variable g:autoInc_VIP to 0. >
354
355     let g:autoInc_VIP = 0 " auto-incrementation disabled
356     let g:autoInc_VIP = 1 " auto-incrementation allowed
357 <
358
359 Add to your vimrc file any variable you want to change permanently.
360
361 You can remap the commands to any key you want by using the "nmap" command.
362 For example, you can add to your vimrc file :
363
364 nmap <F2> :Viy<CR>
365 nmap <F3> :Vie<CR>
366 nmap <F4> :Vic<CR>
367 nmap <F5> :Vii<CR>
368
369 Note : don't use <F1>, it is already used for help.
370
371
372 ==============================================================================
373 CONTACT                                                          *vip-contact*
374
375 Download          : http://www.vim.org/scripts/
376 Contact, feedback : http://www.microreflexion.com/?page_id=9
377 Source code       : http://gitorious.org/vip
378
379
380 ==============================================================================
381 LICENSE                                                          *vip-license*
382 >
383     Copyright (C) 2010 JP Ricaud
384
385     This program is free software: you can redistribute it and/or modify
386     it under the terms of the GNU Lesser General Public License as published by
387     the Free Software Foundation, either version 3 of the License, or
388     (at your option) any later version.
389
390     This program is distributed in the hope that it will be useful,
391     but WITHOUT ANY WARRANTY; without even the implied warranty of
392     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
393     GNU Lesser General Public License for more details.
394
395     http://www.gnu.org/licenses/
396 <
397
398 ==============================================================================
399 HISTORY                                                          *vip-history*
400
401 Version 0.1.7 ; nov. 19 2010 ~
402 ----------------------------
403  - Fixed generic() parser
404
405
406 Version 0.1.6 ; nov. 17 2010 ~
407 ----------------------------
408  - Added verification of existing global variable
409  - Added verification of comment lines
410  - Fixed ; after generic brace
411  - Documentation updated
412
413
414 Version 0.1.5 ; nov. 16 2010 ~
415 ----------------------------
416  - Added auto-incrementation on / off
417  - Documentation updated
418
419
420 Version 0.1.4 ; nov. 14 2010 ~
421 ----------------------------
422  - Added auto-incrementation of instance name
423  - Documentation updated
424
425
426 Version 0.1.3 ; nov. 14 2010 ~
427 ----------------------------
428  - Added global variable for signal prefix, instance's name suffix, entity
429      and component name
430  - Documentation updated
431
432
433 Version 0.1.2 ; nov. 13 2010 ~
434 ----------------------------
435  - Added check for cases where the closing brace is preceded with another
436      brace like (m downto n));
437
438
439 Version 0.1.1 ; nov. 11 2010 ~
440 ----------------------------
441  - Check for empty line in function CheckType()
442  - Check for line with only ")" and ");" in function CheckType()
443  - Check for missing ");" in function CheckType()
444
445
446 Version 0.1.0 ; nov. 08 2010 ~
447 ----------------------------
448  - First alpha release
449
450 vim:tw=78:ts=8:ft=help:norl