Subversion Repositories ssbcc

################################################################################

#

# Copyright 2012-2014, Sinclair R.F., Inc.

#

################################################################################

from ssbccPeripheral import SSBCCperipheral

from ssbccUtil import SSBCCException;

class PWM_8bit(SSBCCperipheral):

  """

  Pulse Width Modulator (PWM) with 8-bit control.\n

  This peripheral creates one or more PWMs.  The PWM is designed so that it is

  allways off when the control is 0 and it is always on when the control is

  0xFF.\n

  Usage:

    PERIPHERAL PWM_8bit   outport=O_name \\

                          outsignal=o_name \\

                          ratemethod={clk/rate|count} \\

                          [invert|noinvert] \\

                          [instances=n] \\

                          [norunt]\n

  Where:

    outport=O_name

      specifies the symbol used by the outport instruction to write a byte to

      the peripheral

      Note:  The name must start with "O_".

    outsignal=o_name

      specifies the name of the output signal

      Note:  The name must start with "o_".

    ratemethod={clk/rate|count}

      specifies the frequency at which the PWM counter is incremented

      Note:  "clk," "rate," and "count" can be integers or can be declared by

             CONSTANT, LOCALPARARM, or PARAMETER configuration commands.

      Example:  ratemethod=count means to increment the PWM counter once every

                "count" clock cycles.

      Example:  ratemethod=G_CLK_HZ/1_000 means to use the parameter G_CLK_HZ

                (set elsewhere) and a 1,000 Hz update rate to determine the

                number of clock cycles between updates.

    invert|noinvert

      optional configuration command to invert or to not invert the PWM output

      Default:  don't invert the output (i.e., a command of 0 means the output is

                always low)

      Note:  "invert" should be used when pulling the external signal to ground

             means the device is "on"

    instances=n

      specifies the number of PWMs for the peripheral

      Default:  The default is one PWM control and output.

    norunt

      optionally add logic to ensure "runt" pulses are not generated by

      incorporating new PWM commands at the start of the counting cycle

      Default:  "runt" pulses are allowed.\n

  The following OUTPORT is provided by this peripheral when instances=1:

    O_name

      output the next 8-bit value to transmit or to queue for transmission\n

  The following OUTPORT is provided by this peripheral when instances=n is larger

  than 1:

    O_name_0, O_name_1, ..., O_name_{n-1}

      output the next 8-bit value to transmit on the specified PWM

      Note:  O_name_i = ${O_name_0+i) where 0<=i<n.

      Note:  The PWM for o_name[i] is controlled by the outport O_name_i

      Example:  If "instances=3" is specified, then the following outports are

                provided:  O_name_0, O_name_1, and O_name_2.  The assembly

                sequence "5 .outport(O_name_1)" will change the PWM control for

                the second of these three PWMs to 5.\n

  Note:  The PWM counter is an 8-bit count that ranges from 1 to 255.  Each PWM

         output is '1' when this count is less than or equal to the commanded

         count.  The signal for a commanded count of 0 will never be on while

         the signal for a commanded count of 255 will always be on.\n

  Example:  Control the intensity of an LED through a PWM.  The LED must flicker

            at a frequency greater than about 30 Hz in order for the flickering

            to not be visible by human eyes.  The LED is turned on when the

            signal to the LED is at ground.  The processor clock frequency is

            provided by the parameter G_CLK_FREQ_HZ.\n

    Within the processor architecture file include the configuration command:\n

    PERIPHERAL PWM_8bit   outport=O_PWM_LED                     \\

                          outsignal=o_led                       \\

                          ratemethod=G_CLK_FREQ_HZ/(30*255)     \\

                          invert\n

    Use the following assembly to set the LED to about 1/4 intensity:\n

    0x40 .outport(O_PWM_LED)\n

  Example:  Similarly to obove, but for the three controls of a tri-color LED:\n

    Within the processor architecture file include the configuration command:\n

    PERIPHERAL PWM_8bit   outport=O_PWM_LED                     \\

                          outsignal=o_led                       \\

                          ratemethod=G_CLK_FREQ_HZ/(30*255)     \\

                          invert                                \\

                          instances=3\n

    Use the following assembly to set the LED intensities to 0x10 0x20 and 0x55:\n

    0x10 .outport(O_PWM_LED_0)

    0x20 .outport(O_PWM_LED_1)

    0x55 .outport(O_PWM_LED_2)\n

    or use the following function to send the three values on the stack where

    the top of the stack is 0x55 0x20 0x10 (this isn't less code, but it

    illustrates how to increment the outport index):\n

    ; ( u_pwm_led_2 u_pwm_led_1 u_pwm_led_0 - )

    .function set_pwm_led

      O_PWM_LED_0 ${3-1} :loop r> swap over outport drop 1+ r> .jumpc(loop,1-) drop

    .return(drop)

  """

  def __init__(self,peripheralFile,config,param_list,loc):

    # Use the externally provided file name for the peripheral

    self.peripheralFile = peripheralFile;

    # Get the parameters.

    allowables = (

      ( 'outport',      r'O_\w+$',      None,   ),

      ( 'outsignal',    r'o_\w+$',      None,   ),

      ( 'ratemethod',   r'\S+$',        lambda v : self.RateMethod(config,v), ),

      ( 'invert',       None,           True,   ),

      ( 'noinvert',     None,           True,   ),

      ( 'instances',    r'[1-9]\d*$',   int,    ),

      ( 'norunt',       None,           True,   ),

    );

    names = [a[0] for a in allowables];

    for param_tuple in param_list:

      param = param_tuple[0];

      if param not in names:

        raise SSBCCException('Unrecognized parameter "%s" at %s' % (param,loc,));

      param_test = allowables[names.index(param)];

      self.AddAttr(config,param,param_tuple[1],param_test[1],loc,param_test[2]);

    # Ensure the required parameters are provided.

    for paramname in (

        'outport',

        'outsignal',

        'ratemethod',

      ):

      if not hasattr(self,paramname):

        raise SSBCCException('Required parameter "%s" is missing at %s' % (paramname,loc,));

    # Set optional parameters.

    for optionalpair in (

        ( 'instances',  1,      ),

        ( 'norunt',     False,  ),

      ):

      if not hasattr(self,optionalpair[0]):

        setattr(self,optionalpair[0],optionalpair[1]);

    # Ensure exclusive pair configurations are set and consistent.

    for exclusivepair in (

        ( 'invert',     'noinvert',     'noinvert',     True,   ),

      ):

      if hasattr(self,exclusivepair[0]) and hasattr(self,exclusivepair[1]):

        raise SSBCCException('Only one of "%s" and "%s" can be specified at %s' % (exclusivepair[0],exclusivepair[1],loc,));

      if not hasattr(self,exclusivepair[0]) and not hasattr(self,exclusivepair[1]) and exclusivepair[2]:

        setattr(self,exclusivepair[2],exclusivepair[3]);

    # Add the I/O port, internal signals, and the INPORT and OUTPORT symbols for this peripheral.

    config.AddIO(self.outsignal,self.instances,'output',loc);

    self.ix_outport_0 = config.NOutports();

    if self.instances == 1:

      tmpOutport = self.outport;

      config.AddOutport((tmpOutport,False,),loc);

    else:

      for ixOutPort in range(self.instances):

        tmpOutport = '%s_%d' % (self.outport,ixOutPort,);

        config.AddOutport((tmpOutport,False,),loc);

    # Add the 'clog2' function to the processor (if required).

    config.functions['clog2'] = True;

  def GenVerilog(self,fp,config):

    body = self.LoadCore(self.peripheralFile,'.v');

    output_on = "1'b1";

    output_off = "1'b0";

    if hasattr(self,'invert'):

      output_on = "1'b0";

      output_off = "1'b1";

    for subpair in (

        ( r'\bL__',             'L__@NAME@__',          ),

        ( r'\bgen__',           'gen__@NAME@__',        ),

        ( r'\bs__',             's__@NAME@__',          ),

        ( r'\bix\b',            'ix__@NAME@',           ),

        ( r'@COUNT@',           self.ratemethod,        ),

        ( r'@INSTANCES@',       str(self.instances),    ),

        ( r'@IX_OUTPORT_0@',    str(self.ix_outport_0), ),

        ( r'@OFF@',             output_off,             ),

        ( r'@ON@',              output_on,              ),

        ( r'@NAME@',            self.outsignal,         ),

        ( r'@NORUNT@',          '1\'b1' if self.norunt else '1\'b0', ),

      ):

      body = re.sub(subpair[0],subpair[1],body);

    body = self.GenVerilogFinal(config,body);

    fp.write(body);