File header

Each VHDL source file created in DESY should have a standard header inserted.

Template

VHDL file header template
--------------------------------------------------------------------------------
--          ____  _____________  __                                           --
--         / __ \/ ____/ ___/\ \/ /                 _   _   _                 --
--        / / / / __/  \__ \  \  /                 / \ / \ / \                --
--       / /_/ / /___ ___/ /  / /               = ( M | S | K )=              --
--      /_____/_____//____/  /_/                   \_/ \_/ \_/                --
--                                                                            --
--------------------------------------------------------------------------------
--! @copyright Copyright [YEAR] DESY
--! [LICENSE]
--------------------------------------------------------------------------------
--! @date [DATE]
--! @author [AUTHOR NAME] <[AUTHOR EMAIL]>
--! @author [AUTHOR NAME] <[AUTHOR EMAIL]>
--------------------------------------------------------------------------------
--! @brief [SHORT]
--!
--! [DESCRIPTION]
--------------------------------------------------------------------------------

Fields

In file header dedicated tags are used to identify header fields.

@copyright

Copyright tag with the year and company name.

YEAR

The year when the file was edited last time. e.g. 2021

LICENSE

Information about the license in SPDX format.
e.g. SPDX-License-Identifier: CERN-OHL-W-2.0
@date

Date interval. When the file was created and when the last time was significantly modified. Can be only creation date.

DATE

(ISO 8601) format YYYY-MM-DD,
interval start/end YYYY-MM-DD/YYYY-MM-DD
e.g. 2021-02-14 or 2020-02-14/2021-02-14
@author

Autor of the file. Main author should be on the top. Any other author/contributor should be added below. Other authors can be added with another @author tag or line below. Author field ends at @brief.

AUTHOR NAME

Name of the author, e.g. John Smith

AUTHOR EMAIL

Author email address, e.g. john.smith@desy.de
@brief

Information about the content of the file.

SHORT

(Mandatory) Short description. One line only. In the same line as @brief or line below.

DESCRIPTION

(Optional) Detailed description. Placed after one line break (--!) after SHORT description. Multiple lines allowed. No maximum size defined.

Example

VHDL header example
-------------------------------------------------------------------------------
--          ____  _____________  __                                          --
--         / __ \/ ____/ ___/\ \/ /                 _   _   _                --
--        / / / / __/  \__ \  \  /                 / \ / \ / \               --
--       / /_/ / /___ ___/ /  / /               = ( M | S | K )=             --
--      /_____/_____//____/  /_/                   \_/ \_/ \_/               --
--                                                                           --
-------------------------------------------------------------------------------
--! @copyright Copyright 2021 DESY
--! SPDX-License-Identifier: CERN-OHL-W-2.0
-------------------------------------------------------------------------------
--! @date 2021-02-14
--! @author John Smith <john.smith @desy.de>
-------------------------------------------------------------------------------
--! @brief
--! Simple 2 order FIR filter on 2xDSP48
-------------------------------------------------------------------------------
VHDL header example 2
-------------------------------------------------------------------------------
--          ____  _____________  __                                          --
--         / __ \/ ____/ ___/\ \/ /                 _   _   _                --
--        / / / / __/  \__ \  \  /                 / \ / \ / \               --
--       / /_/ / /___ ___/ /  / /               = ( M | S | K )=             --
--      /_____/_____//____/  /_/                   \_/ \_/ \_/               --
--                                                                           --
-------------------------------------------------------------------------------
--! @copyright Copyright 2021 DESY
--! SPDX-License-Identifier: CERN-OHL-W-2.0
-------------------------------------------------------------------------------
--! @date 2021-02-14/2021-09-22
--! @author
--! John Smith <john.smith @desy.de>
--! Jo Smith <jo.smith @desy.de>
-------------------------------------------------------------------------------
--! @brief
--! Simple 2 order FIR filter on 2xDSP48
--!
--! Filter is pipelined with 4 clock cycled delay.
--! Filter uses coefficients in fix point format 1.1.16.
--!             +----------------+
--!      -------o                |
--!             |       FIR      +---->
--!      -------o                |
--!             +----------------+
--!-------------------------------------------------------------------------------