1    /*!
     2     *  ======== DriverLib ========
     3     *  MSP430 Low-Level Peripheral Driver Support Library
     4     *
     5     *  DriverLib provides low-level peripheral functions that enables simple
     6     *  and efficient control of peripherals found on the MSP430.  The functions
     7     *  are provided in source form to allow maximum reuse in a variety of
     8     *  development environments.
     9     *
    10     *  This module provides the "home page" for DriverLib within the Grace
    11     *  graphical configuration editor.  This enables projects that support
    12     *  graphical configuration to easily integrate with DriverLib.  In particular,
    13     *  for these projects
    14     *  @p(blist)
    15     *      - DriverLib sources are automatically compiled for your specific device
    16     *      - compiler and linker options are automatically added, and
    17     *      - you can easily switch between different versions of DriverLib on
    18     *        a per-project basis
    19     *  @p
    20     *  This support makes it simple to create Code Composer Studio (CCS) projects
    21     *  that enable you to easily build and manage specific versions of pre-built
    22     *  DriveLib libraries.  These pre-built libraries can then be referenced by
    23     *  one or more of your existing projects.
    24     *  
    25     *  @a(Using DriverLib)
    26     *  Using DriverLib is a simple three step process.
    27     *  @p(nlist)
    28     *      - modify your `.c` sources to include the appropriate peripheral header
    29     *        file and call the desired function.
    30     *      - modify your compiler project options to include the directory
    31     *        containing the DriverLib product's root directory.
    32     *      - modify your linker project options to include the path to a
    33     *        pre-built library of the appropriate DriverLib sources.
    34     *  @p
    35     *
    36     *  Suppose, for example, you want to use the WDT_A watchdog timer functions of
    37     *  DriverLib.  Your source might be modified to look like the following:
    38     *  @p(code)
    39     *      #include <driverlib/MSP430FR57xx/wdt_a.h>     // include header for the WDT_A peripheral
    40     *
    41     *      int main(void) {
    42     *          WDT_A_hold(__MSP430_BASEADDRESS_WDT_A__); // disable the WDT_A watchdog timer
    43     *             :
    44     *          return (0);
    45     *      }
    46     *  @p
    47     *
    48     *  If you're using Code Composer Studio (CCS), DriverLib automatically defines
    49     *  a "macro", named `${MSP430_DRIVERLIB_ROOT}`, that should be used to specify
    50     *  include paths.  This ensures  that your projects are portable among users
    51     *  that may have different installation directories.  In this case, your
    52     *  compiler include options should include:
    53     *  @p(code)
    54     *      -I ${MSP430_DRIVERLIB_ROOT}
    55     *  @p
    56     *
    57     *  Finally, suppose you're created a project named `driverlib_5739` which
    58     *  contains a pre-built DriverLib library for the MSP430FR5739.  Your linker
    59     *  options should include:
    60     *  @p(code)
    61     *      -l "${workspace_loc:/driverlib_5739/src/driverlib/driverlib.lib}"
    62     *  @p
    63     *  where, `${workspace_loc: ...}` is an Eclipse/CCS macro that
    64     *  expands to an absolute path to the file `src/driverlib/driverlib.lib`
    65     *  located in the project named `driverlib_5739`.  Again, using the Eclipse
    66     *  `${...}` macros enables projects to be directly imported by other
    67     *  developers even if they have different workspace or product installation
    68     *  paths.
    69     *
    70     *  @a(Building DriverLib)
    71     *  If you are using Code Composer Studio (CCS), it is easy to build a library
    72     *  for a specific device.
    73     *  @p(nlist)
    74     *      - Create a new project: File -> New -> CCS Project
    75     *      - Select a device and a project name, say `MSP430FR5739` and
    76     *        "`driverlib_5739`"
    77     *      - In the "Project templates and examples" selection box, select the
    78     *        "Configurable DriverLib Example" template under the
    79     *        "MSP430 DriverLib" heading.  If you don't see this heading, the
    80     *        device you selected is not supported by DriverLib.
    81     *      - Click the "`Finish`" button.  A new project named `driverlib_5739`
    82     *        will be created and added to your workspace.
    83     *      - Build the project: Project -> Build Project
    84     *  @p
    85     *  Once the project is finished building, a complete DriverLib library, named
    86     *  `driverlib.lib`, will exist in the `./src/driverlib` folder of the project
    87     *  and can be referenced by any other project in your workspace via the
    88     *  Eclipse/CCS macro:
    89     *  @p(code)
    90     *      ${workspace_loc:/driverlib_5739/src/driverlib/driverlib.lib}
    91     *  @p
    92     */
    93    @Template("./DriverLib.xdt")
    94    metaonly module DriverLib
    95    {
    96        /*!
    97         *  ======== BASENAME ========
    98         *  The base name of the pre-built DriverLib library
    99         *  
   100         *  This name controls the name of a pre-built DriverLib library.  For
   101         *  example, if BASENAME is set to "driverlib" the name of the library
   102         *  will be driverlib.lib in the ./src/driverlib folder of your project.
   103         *  
   104         *  @_nodoc
   105         */
   106        const String BASENAME = "driverlib";
   107    
   108        /*!
   109         *  ======== getFamilyPath ========
   110         *  Given a device name, return the path to the device family's sources
   111         *
   112         *  This function returns a path relative to the DriverLib source
   113         *  repository containing the DriverLib sources.  For example,
   114         *  if `deviceName` is `"MSP430FR5969"`, this function returns
   115         *  `"driverlib/MSP430FR5xx_6xx"`.
   116         *
   117         *  The string returned by this function can be used with `getSrcRepo`
   118         *  to obtain the absolute path to the sources for the DriverLib family
   119         *  that supports the device `deviceName`.
   120         *  
   121         *  @see #getSrcRepo
   122         */
   123        String getFamilyPath(String deviceName);
   124    
   125        /*!
   126         *  ======== getLibPath ========
   127         *  Returns the path to a pre-built DriverLib library
   128         *  
   129         *  This function is called by the `getLibs()` method provided by the
   130         *  package containing the DriverLib module.  This `getLibs()` method
   131         *  is implemented in the `package.xs` file and is used to provide the
   132         *  path to a pre-built DriverLib library for any project that uses
   133         *  DriverLib.
   134         *  
   135         *  @_nodoc
   136         */
   137        String getLibPath();
   138    
   139        /*!
   140         *  ======== getSrcRepo ========
   141         *  Given a family path, return the path to it's source repository
   142         *
   143         *  This function returns an absolute path to the repository
   144         *  containing the DriverLib sources for the specified device family.
   145         *
   146         *  @see #getFamilyPath
   147         */
   148        String getSrcRepo(String familyPath);
   149    
   150        /*!
   151         *  ======== outputDir ========
   152         *  The output directory for all generated sources
   153         *
   154         *  The default output directory is the `src/` sub-directory of the
   155         *  directory containing the configuration script used to specify
   156         *  the peripherals for which to generate code.
   157         *
   158         *  This parameter should only be changed when running the
   159         *  configuration tool in a command line environment.  Integrated
   160         *  Development Environments (IDEs) often require that generated sources
   161         *  be placed in specific directories.  Changes to this parameter often
   162         *  require corresponding changes to the IDE.
   163         *
   164         *  @_nodoc
   165         */
   166        config String outputDir;
   167    }