PSoC® Creator™ Component Datasheet Trim and Margin 3.0 Features Works with most adjustable DC-DC converters or regulators, including low-dropouts (LDOs), switchers, and modules Supports positive and negative feedback control loop Supports up to 24 DC-DC converters 8- to 10-bit resolution PWM pseudo-DAC outputs Supports real-time, closed-loop active trimming when used in conjunction with the Power Monitor or ADC component Built-in support for margining General Description The Trim and Margin component provides a simple way to adjust and control the output voltage of up to 24 DC-DC converters to meet system power supply requirements. Users of this component enter the power converter nominal output voltages, voltage trimming range, margin high and margin low settings into the intuitive, graphical configuration GUI and the component calculates all the required parameters for injecting a pulse width modulated signal into the feedback network of a power converter. The component will also assist the user to select appropriate external passive component values based on performance requirements. The provided firmware APIs enable users to manually trim the power converter output voltages to any desired level within the operational limits of the power converter. Real-time active trimming or margining is supported via as a continuously running background task with an update frequency controlled by the user. When to Use a Trim and Margin Component The Trim and Margin component should be used in any application that requires PSoC to adjust and control the output voltage of multiple DC-DC power converters. Use the Trim and Margin component along with other Power Supervision components to build your own custom power supervision solution. Cypress Semiconductor Corporation • 198 Champion Court • San Jose, CA 95134-1709 • 408-943-2600 Document Number: 002-10607 Rev. ** Revised February 2, 2016 PSoC® Creator™ Component Datasheet Trim and Margin Input/Output Connections This section describes the various input and output connections for the Trim and Margin component. An asterisk (*) in the list of I/Os means that the I/O may be hidden on the symbol under the conditions listed in the description of that I/O. clock – Input Clock signal used to drive the PWM pseudo-DAC outputs. enable – Input Active high clock enable synchronous with the clock input. Asserting this signal enables the PWMs. This synchronous active high signal is used as a clock enable to the PWMs. alert – Output Active high signal is asserted when closed loop trimming/margining is not achievable because PWM is at the minimum or maximum duty cycle, but desired power converter output voltage has not been achieved. Remains asserted as long as the alert condition exists on any output. Note This terminal is only available on devices that contain the UDB array. You still can monitor the alert status in firmware by calling TrimMargin_GetAlertSource() API function. trim[1..24] – Output * These terminals are the PWM outputs that pass through an external RC filter to produce an analog control voltage that adjusts the output voltage of the associated power converter. The number of these terminals depends on Number of converters parameter. Schematic Macro Information This section contains pertinent information regarding the Trim and Margin component schematic macros. Schematic Macro Name Purpose Description Trim and Margin – 8 Rails Intended to be competitive with most off-the-shelf, 8 rail Power Supervisor ASSPs. Supports 8 outputs and the component is configured for 8-bit resolution. Clock input is set to 24 MHz. Trim and Margin – 16 Rails Intended to be competitive with newer off-the-shelf, 16 rail Power Supervisor ASSPs Supports 16 outputs and the component is configured for 8-bit resolution. Clock input is set to 24 MHz. Trim and Margin – 24 Rails Intended to demonstrate PSoC’s ability Supports 24 outputs and the component is to implement a full-featured Power configured for 8-bit resolution. Clock input is Supervisor with support for more power set to 24 MHz converters than any other competitor. Page 2 of 27 Document Number: 002-10607 Rev. ** PSoC® Creator™ Component Datasheet Trim and Margin - 8 Rails Document Number: 002-10607 Rev. ** Trim and Margin Trim and Margin - 16 Rails Trim and Margin - 24 Rails Page 3 of 27 Trim and Margin PSoC® Creator™ Component Datasheet Component Parameters Drag a Trim and Margin component onto your design and double click it to open the Configure dialog. This dialog has the following tabs with different parameters. Summary Tab The summary tab shows a summary of all the rails that requires trim/margin. The table is read only. Double click the table or press the “Add Converter”, “Delete Converter” or “Configure” to change it. Toolbar Copy/Paste – Copies the selected row in the table and pastes the same data on the table. Keyboard shortcut (copy) – [Ctrl] [C] Keyboard shortcut (paste) – [Ctrl] [V] Load configuration – Restores all customizer settings, including table, from an external file. Supports XML file format. Keyboard shortcut – [Ctrl] [L] Store configuration – Stores all customizer settings, including tables, in an external XML file. Keyboard shortcut – [Ctrl] [S] Add converter – Adds a converter in the summary table. A dialog window opens to input the converter configuration. Delete converter – Deletes a converter in the summary table. You need to select the converter to be deleted. If no converter is selected, this button is grayed out. Page 4 of 27 Document Number: 002-10607 Rev. ** PSoC® Creator™ Component Datasheet Trim and Margin Configure converter – Opens a configuration window for the selected power converter. If no converter is selected, this button is grayed out. Show/Hide columns – Opens a list of all the columns shown in the table. You can choose the columns to display. Number of converters Number of converters to trim and margin. The number increases or decreases when adding and deleting rails from the table. Controller method Use this parameter to choose between the following types of controllers when actively trimming: Incremental or Integral. The Incremental controller is limited to increment or decrement based on the difference between actual and desired voltage and the converter feedback. The response of this controller is very slow when the desired voltage is significantly different from an actual voltage. The integral controller (I Control) is a type of a PID Controller with the P (proportional) and D (derivative) gain terms set to zero. This type of controller has better response time compared to the Incremental option. Refer to Functional Description section for more information about the Integral controller method. The default setting is Incremental. PWM Resolution Resolution of the PWM pseudo-DAC outputs. Selectable between 8 through 10 bits to enable users to select an optimal tradeoff between granularity of control voltage and PWM output frequency. This configuration applies to all rails. Range = 8, 9, 10 bits (default 8). PWM Frequency Calculated PWM output frequency based on the input clock and PWM resolution. f PWM f CLOCK , n is PWM resolution. 2n PWM Implementation Use this parameter to choose between a fixed-function timer/counter/PWM (TCPWM) implementation and a UDB implementation of the internal PWMs. If the target device does not have a UDB array, the UDB option cannot be selected. If the device does not have any TCPWM Document Number: 002-10607 Rev. ** Page 5 of 27 Trim and Margin PSoC® Creator™ Component Datasheet blocks, the Fixed Function option cannot be selected. This parameter is only applicable for the PSoC 4 device family. Configure Window This window is opened by pressing the Add Converter or Configure button, or by doubleclicking the desired converter row in the summary table. Converter name This is a text field, 16 characters. For annotation purposes only to relate the PWM outputs of this component to the functions of the power converters they control. Feedback This parameter determines the voltage adjust feedback input polarity from the power converter. This will decide if increasing the PWM duty cycle will increase (Positive) or decrease (Negative) the converter output voltage. Options = Positive, Negative (default). Page 6 of 27 Document Number: 002-10607 Rev. ** PSoC® Creator™ Component Datasheet Trim and Margin Control sample time This is the period time in milliseconds for how often this power converter is trimmed, that is, the TrimMargin_ActiveTrim() API is called for this converter. This time has to be on average three times longer than the time it takes to scan the voltage output of the converter (filters should also be taken in consideration). For example, the Power Monitor takes in average 150 µs per rail to measure the voltage. If the Power Monitor is configured to scan 16 rails and use an average filter of 8 samples, the recommended control sample time is: 𝑐𝑡 = 150 𝜇𝑠 × 8 × 16 × 3 = 57.6 𝑚𝑠 This parameter is only available when the Integral option is selected for the Controller method parameter. Range = 1..65,535 ms. Default value is 100 ms. Nominal voltage (V) Nominal converter output voltage. Range = 0.001..65.535 V. Margin low (%) Desired converter output voltage in response to a margin low request. This value is entered in percent of nominal voltage. The calculated value is displayed below in the Margin low (V) field. Range = -100.00..0 %. Margin high (%) Desired converter output voltage in response to a margin high request. This value is entered in percent of nominal voltage. The calculated value is displayed below in the Margin high (V) field. Range = 0..100.00 %. Max. voltage (V) Maximum converter output voltage. Impacts external components to achieve the high side of the desired dynamic range. Range = 0.001..65.535 V. Min. voltage (V) Minimum converter output voltage. Impacts external components to achieve the low side of the desired dynamic range. Range = 0.001..65.535 V. Startup voltage (V) User configurable startup voltage for the converter. The PWM duty cycle is set to pre-run value to achieve the startup voltage when the component is initialized by calling the TrimMargin_Init() API. Range = 0.001..65.535 V. Document Number: 002-10607 Rev. ** Page 7 of 27 Trim and Margin PSoC® Creator™ Component Datasheet Voh of PWM output (V) The output voltage that will be used with the associated PWM pin. It can be the Vddio for a GPIO pin or an internal Vref for SIO pin. Range = 0.001..5.5 V. Nominal Vadj voltage Control voltage at the adjust/feedback control pin to achieve nominal output voltage based on power converter datasheet specification. Range = 0.001..65.535 V. Desired Vout ripple Specifies the maximum ripple that appears on the output of the voltage regulator. The ripple effect comes from the RC circuit designed to trim/margin the converter. Range = 0.001..100.000 mV. Resistor E Series Specifies preferred E series for the external resistors on your PCB. The calculated resistor values will be rounded up to the closest nominal values from the specified E series. Range = E24, E48, E96 or E192 (default). Capacitor E Series Specifies preferred E series for the external capacitor on your PCB. The calculated capacitor value will be rounded up to the closest nominal value from the specified E series. Range = E24, E48, E96 or E192 (default). R1 (kOhm) External scaling resistor value (in kΩ) to achieve the correct voltage on adjust/feedback control pin required for the nominal output voltage when the PWM output is disabled. This value comes from user’s PCB based on power converter datasheet specifications. Range = 0.001..100,000 kΩ. R2 (kOhm) / Calculated R2 (kOhm) External scaling resistor value (in kΩ) to achieve the correct voltage on adjust/feedback control pin required for the nominal output voltage when the PWM output is disabled. This value comes from user’s PCB based on power converter datasheet specifications. If the checkbox on the right side is unchecked, the value of R2 is calculated automatically and overrides the current R2 value. The value belongs to the specified Resistor E series. Range = 0.001..65,535 kΩ. Page 8 of 27 Document Number: 002-10607 Rev. ** PSoC® Creator™ Component Datasheet Trim and Margin R3 (kOhm)/ Calculated R3 (kOhm) The actual resistor value used on the PCB in order to calculate the actual dynamic range. If the checkbox on the right side is unchecked, the value of R3 is calculated automatically and overrides the current R3 value. The value belongs to the specified Resistor E series. Range = 0.001..65,535 kΩ. It is recommended to have R3 > 10 × R4 to avoid instability on the converter response. Combining this recommendation with Rserial = R3 + R4, R3 is calculated as R3 = Rserial × 10/11. R4 (kOhm) / Calculated R4 (kOhm) The actual resistor value used on the PCB in order to calculate the actual dynamic range. If the checkbox on the right side is unchecked, the value of R4 is calculated automatically and overrides the current R4 value. The value belongs to the specified Resistor E series. Range = 0.001..65,535 kΩ. The resistor R4 is calculated as R4 = Rserial - R3. C1 (µF) / Calculated C1 (µF) The actual capacitor value use on the PCB in order to calculate the actual ripple. If the checkbox on the right side is unchecked, the value of C1 is calculated automatically and overrides the current C1 value. The value belongs to the specified Capacitor E series. Range = 0.001..65.535 µF. The capacitor C1 is calculated as: C1 VOH R1 2 R 4 f PWM Vripple R3 Calculated ideal value for R2 (kOhm) The ideal value for R2 depends on the Feedback parameter and is calculated as: Negative feedback: R2 Positive feedback: R2 R1 (VOH VOH (VREF R1 VADJ Rserial VADJ ) Rserial (VMIN VADJ ) R1 VOH VMIN VMIN ) VREF (VMAX VMIN ) Calculated ideal value for R3 + R4 (kOhm) The value is dependent on the Feedback parameter and is calculated as: VOH VMAX VMIN Negative feedback: R3 R 4 Rserial R1 Document Number: 002-10607 Rev. ** Page 9 of 27 PSoC® Creator™ Component Datasheet Trim and Margin Positive feedback: R3 R 4 Rserial VOH R1 VMAX 1 VREF VMIN Actual R3+R4 (kOhm) Sum of the actual resistance values selected in the customizer for R3 and R4. Actual Vout ripple (mV) The actual value for Vout ripple is calculated as: Vripple VDDIO R1 2 R4 f PWM C1 R3 Calculated Max. voltage (V) Depending on the Feedback parameter, the actual value of the maximum output voltage for the given circuit is calculated as: R1 R1 Negative feedback: VMAX VADJ 1 R 2 Rserial Positive feedback: VMAX VREF VOH 2 n 1 n R1 Rserial 2 1 1 1 R1 R 2 Rserial Calculated Min. voltage (V) The actual value of the minimum output voltage for the given circuit depends on the Feedback parameter, and is calculated as: R1 2 n 1 R1 R1 V V 1 V n Negative feedback: MIN ADJ R2 R OH R 2 serial serial where n is PWM resolution. Positive feedback: VMIN Page 10 of 27 VREF R1 1 1 1 R1 R 2 Rserial Document Number: 002-10607 Rev. ** PSoC® Creator™ Component Datasheet Trim and Margin Application Programming Interface Application Programming Interface (API) routines allow you to configure and control the component using software. The following table lists and describes the interface to each function. The subsequent sections cover each function in more detail. By default, PSoC Creator assigns the instance name "TrimMargin_1" to the first instance of a component in a given design. You can rename it to any unique value that follows the syntactic rules for identifiers. The instance name becomes the prefix of every global function name, variable, and constant symbol. For readability, the instance name used in the following tables is "TrimMargin". Functions Function Description TrimMargin_Start() Starts the component operation. TrimMargin_Stop() Disables the component. TrimMargin_Init() Initializes component's parameters. TrimMargin_Enable() Enables the generation of PWMs outputs. TrimMargin_SetMarginHighVoltage() Sets the margin high output voltage parameter. TrimMargin_GetMarginHighVoltage() Returns the margin high output voltage parameter. TrimMargin_SetMarginLowVoltage() Sets the margin low output voltage parameter. TrimMargin_GetMarginLowVoltage() Returns the margin low output voltage parameter. TrimMargin_SetNominalVoltage() Sets the nominal output voltage parameter. TrimMargin_GetNominalVoltage() Returns the nominal output voltage parameter. TrimMargin_ActiveTrim() Adjusts the PWM duty cycle of the specified power converter to get the power converter actual voltage output closer to the desired voltage output. TrimMargin_SetDutyCycle() Sets PWM duty cycle of the PWM associated with the specified power converter. TrimMargin_GetDutyCycle() Gets the current PWM duty cycle of the PWM associated with the specified power converter. TrimMargin_GetAlertSource() Returns a bit mask indicating which PWMs are generating an alert. TrimMargin_MarginHigh() Sets power converter output voltage to the Margin high voltage. TrimMargin_MarginLow() Sets power converter output voltage to the Margin low voltage. TrimMargin_Nominal() Sets power converter output voltage to the Nominal voltage. Document Number: 002-10607 Rev. ** Page 11 of 27 PSoC® Creator™ Component Datasheet Trim and Margin Function Description TrimMargin_PreRun() Sets the pre-charge PWM duty cycle required to achieve nominal voltage before the power converter is enabled. TrimMargin_Startup() Sets power converter output voltage to the Startup voltage. TrimMargin_StartupPreRun() Sets the pre-charge PWM duty cycle to achieve the Startup voltage before power converter is enabled. TrimMargin_ConvertVoltageToDutyCycle() Returns the PWM duty cycle required to achieve the desired voltage on the selected power converter. TrimMargin_ConvertVoltageToPreRunDutyCycle() Returns the pre-charge PWM duty cycle required to achieve the desired voltage on the selected power converter. TrimMargin_SetTrimCycleCount() Set the internal trim cycle counter that affects how often the PWM duty cycle is updated when calling TrimMargin_ActiveTrim() API. Applicable for Incremental controller type only. void TrimMargin_Start(void) Description: Starts the component operation. Calls the TrimMargin_Init() API if the component has not been initialized before. Calls TrimMargin_Enable() API. Parameters: None Return Value: None Side Effects: None void TrimMargin_Stop(void) Description: Disables the component. Stops the PWMs. trim[x] outputs halted in an undefined state. Use the pin-specific API PinName_SetDriveMode(PIN_DM_DIG_HIZ) to change the drive mode of the connected to these outputs pins to High Impedance Digital. Parameters: None Return Value: None Side Effects: Page 12 of 27 None Document Number: 002-10607 Rev. ** PSoC® Creator™ Component Datasheet Trim and Margin void TrimMargin_Init(void) Description: Initializes component's parameters to those set in the customizer. It is not necessary to call TrimMargin_Init() because the TrimMargin_Start() routine calls this function, which is the preferred method to begin the component operation. PWM duty cycles are set to pre-run values to achieve the startup voltage target assuming that the power converters are not yet turned on (disabled). Parameters: None Return Value: None Side Effects: None void TrimMargin_Enable(void) Description: Enables PWMs outputs generation. Parameters: None Return Value: None Side Effects: None void TrimMargin_SetMarginHighVoltage(uint8 converterNum, uint16 marginHiVoltage) Description: Sets the margin high output voltage of the specified power converter. This overrides the present vMarginHigh[x] setting and recalculates vMarginHighDutyCycle[x] to be ready for use by TrimMargin_MarginHigh(). Note: calling this API does NOT cause any change in the PWM output duty cycle. Parameters: converterNum: Specifies the power converter number. Valid range: 1..24 marginHiVoltage: Specifies the desired power converter output margin high voltage in mV. Valid range: 1..65,535 Return Value: None Side Effects: None uint16 TrimMargin_GetMarginHighVoltage(uint8 converterNum) Description: Returns the margin high output voltage of the specified power converter Parameters: converterNum: Specifies the power converter number. Valid range: 1..24 Return Value: Power converter margin high output voltage in mV. Side Effects: None Document Number: 002-10607 Rev. ** Page 13 of 27 PSoC® Creator™ Component Datasheet Trim and Margin void TrimMargin_SetMarginLowVoltage(uint8 converterNum, uint16 marginLoVoltage) Description: Sets the margin low output voltage of the specified power converter. This overrides the present vMarginLow[x] setting and recalculates vMarginLowDutyCycle[x] to be ready for use by TrimMargin_MarginLow(). Note Calling this API does NOT cause any change in the PWM output duty cycle. Parameters: converterNum: Specifies the power converter number. Valid range: 1..24 marginLoVoltage: Specifies the desired power converter output margin low voltage in mV. Valid range: 1..65,535 Return Value: None Side Effects: None uint16 TrimMargin_GetMarginLowVoltage(uint8 converterNum) Description: Returns the margin low output voltage of the specified power converter. Parameters: converterNum: Specifies the power converter number. Valid range: 1..24 Return Value: Power converter margin low output voltage in mV. Side Effects: None void TrimMargin_SetNominalVoltage(uint8 converterNum, uint16 nominalVoltage) Description: Sets the nominal output voltage of the specified power converter. This overrides the present vNom[x] setting and recalculates vNominalDutyCycle to be ready for use by TrimMargin_Nominal(). Note Calling this API does NOT cause any change in the PWM output duty cycle. Parameters: converterNum: Specifies the power converter number. Valid range: 1..24 nominalVoltage: Specifies the desired power converter output margin low voltage in mV. Valid range: 1..65,535 Return Value: None Side Effects: None uint16 TrimMargin_GetNominalVoltage(uint8 converterNum) Description: Returns the margin low output voltage of the specified power converter. Parameters: converterNum: Specifies the power converter number. Valid range: 1..24 Return Value: Power converter nominal output voltage in mV. Side Effects: Page 14 of 27 None Document Number: 002-10607 Rev. ** PSoC® Creator™ Component Datasheet Trim and Margin void TrimMargin_ActiveTrim(uint8 converterNum, uint16 actualVoltage, uint16 desiredVoltage) Description: Adjusts the PWM duty cycle of the specified power converter to get the power converter actual voltage output closer to the desired voltage output. It needs to be called on a regular basis to ensure proper closed-loop regulation is achieved. If the integral controller is used, the time between two consecutive calls is based on the Control sample time parameter provided in the GUI. If the incremental controller is used, the adjustments rely on an internal counter set by the SetTrimCycleCount() API. The implementation is dependent on the Controller method parameter. Parameters: converterNum: Specifies the power converter number. Valid range: 1..24 actualVoltage: Specifies the current actual power converter output voltage reading in mV. This value can be obtained using the Power Monitor component connected to the power converter output voltage. Valid range: 1..65,535 desiredVoltage: Specifies the desired power converter output voltage in mV. Valid range: 1..65,535 Return Value: None Side Effects: Calling this API may change the PWM duty cycle driving the control voltage of the selected power converter causing the change in the power converter output voltage. If the desiredVoltage cannot be achieved because the PWM duty cycle is at the min or max level, the alert signal will be asserted until the alert condition is removed, only possible by calling this API with achievable desiredVoltage. void TrimMargin_SetDutyCycle(uint8 converterNum, uint8/uint16 dutyCycle) Description: Sets the PWM duty cycle of the PWM associated with the specified power converter. The PWM period is always fixed at the maximum value depending on the resolutions set in the customizer. Parameters: converterNum: Specifies the power converter number. Valid range: 1..24 Specifies the PWM duty cycle in PWM clock counts. Valid range: 0..255 (uint8) up to 0..1023 (uint16) depending on the PWM resolution set in the customizer. Return Value: None Side Effects: None Document Number: 002-10607 Rev. ** Page 15 of 27 PSoC® Creator™ Component Datasheet Trim and Margin uint8/uint16 TrimMargin_GetDutyCycle(uint8 converterNum) Description: Gets the current duty cycle of the PWM associated with the specified power converter. Note that if the TrimMargin_ActiveTrim() API is being called regularly, the value returned should be expected to change over time. Parameters: converterNum. Specifies the power converter number. Valid range: 1..24 Return Value: PWM duty cycle in PWM clock counts. Valid range: 0..255 (uint8) up to 0..1023 (uint16) depending on the resolution set in the customizer. Side Effects: None uint8/uint16/uint32 TrimMargin_GetAlertSource(void) Description: Returns a bit mask indicating which PWMs are generating an alert Parameters: None Return Value: uint8/uint16/uint32. Bit Field bit0 1 = Failure to achieve power converter regulation on trim1 output bit1 1 = Failure to achieve power converter regulation on trim2 output … bit23 Side Effects: Alert Source … 1 = Failure to achieve power converter regulation on trim24 output None void TrimMargin_MarginHigh(uint8 converterNum) Description: Sets the selected power converter output voltage to the desired margin high setting as specified in the customizer or be calling TrimMargin_SetMarginHighVoltage() API. Parameters: uint8 converterNum. Specifies the power converter number Valid range: 1..24 Return Value: None Side Effects: None void TrimMargin_MarginLow(uint8 converterNum) Description: Sets the selected power converter output voltage to the desired margin low setting as specified in the customizer or be calling TrimMargin_SetMarginLowVoltage() API. Parameters: converterNum: Specifies the power converter number. Valid range: 1..24 Return Value: None Side Effects: Page 16 of 27 None Document Number: 002-10607 Rev. ** PSoC® Creator™ Component Datasheet Trim and Margin void TrimMargin_Nominal(uint8 converterNum) Description: Sets the selected power converter output voltage to the desired margin low setting as specified in the customizer or be calling TrimMargin_SetNominalVoltage() API. Parameters: converterNum: Specifies the power converter number. Valid range: 1..24 Return Value: None Side Effects: None void TrimMargin_PreRun(uint8 converterNum) Description: Sets the pre-charge PWM duty cycle required to achieve nominal voltage before power converter is enabled with the assumption that the R1 is grounded in parallel with R2. Parameters: converterNum: Specifies the power converter number. Valid range: 1..24 Return Value: None Side Effects: None void TrimMargin_Startup(uint8 converterNum) Description: Sets the selected power converter output voltage to the startup voltage setting as specified in the customizer. Parameters: converterNum: Specifies the power converter number. Valid range: 1..24 Return Value: None Side Effects: None void TrimMargin_StartupPreRun(uint8 converterNum) Description: Sets the pre-charge PWM duty cycle required to achieve the startup voltage before the power converter is enabled with the assumption that R1 is grounded in parallel with R2. Parameters: converterNum: Specifies the power converter number. Valid range: 1..24 Return Value: None Side Effects: None Document Number: 002-10607 Rev. ** Page 17 of 27 PSoC® Creator™ Component Datasheet Trim and Margin uint8/uint16 TrimMargin_ConvertVoltageToDutyCycle(uint8 converterNum, uint16 desiredVoltage) Description: Returns the PWM duty cycle required to achieve the desired voltage on the selected power converter. The PWM duty cycle for the specified output voltage is dependent on the corresponding power converter and is calculated as: Negative feedback: D VMAX Vout (2n 1) VMAX VMIN Positive feedback: D Vout VMIN (2 n 1) VMAX VMIN Where VMAX and VMIN are calculated maximum and minimum output voltages for the given power converter, and n is the PWM resolution. Parameters: converterNum: Specifies the power converter number. Valid range: 1..24 desiredVoltage. Specifies the desired power converter output voltage in mV. Return Value: PWM duty cycle in PWM clock counts. Valid range: 0..255 (uint8) up to 0..1023 (uint16) depending on the resolution set in the customizer. Side Effects: None uint8/uint16 TrimMargin_ConvertVoltageToPreRunDutyCycle(uint8 converterNum, uint16 desiredVoltage) Description: Returns the pre-charge PWM duty cycle required to achieve the desired voltage on the selected power converter. Parameters: converterNum: Specifies the power converter number. Valid range: 1..24 desiredVoltage: Specifies the desired power converter output voltage in mV. Return Value: PWM duty cycle in PWM clock counts. Valid range: 0..255 (uint8) up to 0..1023 (uint16) depending on the resolution set in the customizer. Side Effects: Page 18 of 27 None Document Number: 002-10607 Rev. ** PSoC® Creator™ Component Datasheet Trim and Margin void TrimMargin_SetTrimCycleCount(uint8 count) Description: Sets the internal adjustment cycle count that affects how often the PWM duty cycle is updated when calling TrimMargin_ActiveTrim() API. The default value is TrimMargin_CYCLE_SLOW. The API is only applicable if Incremental option is selected for the Controller method parameter. Parameters: count: Specifies the cycle count value. Macro name Value TrimMargin_CYCLE_SLOW 20 TriMargin_CYCLE_MEDIUM 15 TrimMargin_CYCLE_FAST 10 Return Value: None Side Effects: None Global Variables Function Description TrimMargin_initVar Indicates whether the component has been initialized. It is initialized to zero and set to one the first time TrimMargin_Start() is called. This allows a component restart without re-initialization in all subsequent calls to the TrimMargin_Start() routine. TrimMargin_vMarginLow[] Margin low output voltage for all power converters. Initialized by Init() function with the customizer settings. Can be changed at run time by calling SetMarginLowVoltage() function. TrimMargin_vMarginHigh[] Margin high output voltage for all power converters. Initialized by Init() function with the customizer settings. Can be changed at run time by calling SetMarginHighVoltage() function. TrimMargin_vNom[] Nominal output voltage for all power converters. Initialized by Init() function with the customizer settings. Can be changed at run time by calling SetNominalVoltage() function. TrimMargin_vMarginLowDutyCycle[] The PWM duty cycle for the margin low output voltage. Initialized with customizer settings in Init(). Recalculated in SetMarginLowVoltage() when a new value is set. Used by MarginLow() to set PWM for the open loop margin. TrimMargin_vMarginHighDutyCycle[] The PWM duty cycle for the margin low output voltage. Initialized with customizer settings in Init(). Recalculated in SetMarginHighVoltage() when a new value is set. Used by MarginHigh() to set PWM for the open loop margin. TrimMargin_vNominalDutyCycle[] The PWM duty cycle for the margin low output voltage. Initialized with customizer settings in Init(). Recalculated in SetNominalVoltage() when a new value is set. Used by Nominal() to set PWM for the open loop margin. Document Number: 002-10607 Rev. ** Page 19 of 27 PSoC® Creator™ Component Datasheet Trim and Margin Example Projects, Code Examples, and Application Notes Example Projects PSoC Creator provides access to example projects in the Find Example Project dialog. For component-specific examples, open the dialog from the Component Catalog or an instance of the component in a schematic. For general examples, open the dialog from the Start Page or File menu. As needed, use the Filter Options in the dialog to narrow the list of projects available to select. Refer to the "Find Example Project" topic in the PSoC Creator Help for more information. Code Examples There are numerous code example projects that include schematics and example code available online at the Cypress Code Examples web page. Code Example CE95387 - Trim voltage rails with PSoC 3/5LP demonstrates the basic operation of the Trim Margin component. Application Notes Cypress provides a number of application notes describing how PSoC can be integrated into your design. You can access the Cypress Application Notes search web page (www.cypress.com/appnotes). AN93529 - Introduction to Power Supervision with PSoC 5LP demonstrates how to configure a fully-featured Power Supervision solution using the PSoC Power Supervision Tool. Note this application note is not posted publically. Please contact Cypress technical support to obtain this document. Deprecated code The Trim and Margin component contains deprecated code that is not recommended for use but is kept to preserve backward compatibility with the existing designs. The deprecated code is located under the next comment header in the component source files: /*************************************** * The following code is DEPRECATED and * should not be used in new projects. ***************************************/ Follow instructions in the following table on how to update your design. What is deprecated TrimMargin_SetNominal(n) TrimMargin_SetPreRun(n) TrimMargin_SetStartup(n) Reason for deprecation Updated naming convention for consistency and addition of new APIs. How to handle it Use TrimMargin_Nominal(n) Use TrimMargin_PreRun(n) Use TrimMargin_Startup(n) TrimMargin_SetStartupPreRun(n) Use TrimMargin_StartupPreRun(n) TrimMargin_DUTYCYCLE Use TrimMargin_VNOMINAL_DUTYCYCLE Page 20 of 27 Document Number: 002-10607 Rev. ** PSoC® Creator™ Component Datasheet What is deprecated Trim and Margin Reason for deprecation TrimMargin_TRIM_SLOW_PERIOD How to handle it Use TrimMargin_TRIM_CYCLE_SLOW API Memory Usage The component memory usage varies significantly, depending on the compiler, device, number of APIs used and component configuration. The following table provides the memory usage for all APIs available in the given component configuration. The measurements have been done with the associated compiler configured in Release mode with optimization set for Size. For a specific design, the map file generated by the compiler can be analyzed to determine the memory usage. PSoC 3 (Keil_PK51) Configuration PSoC 4 (GCC) PSoC 5LP (GCC) Flash Bytes SRAM Bytes Flash Bytes SRAM Bytes Flash Bytes SRAM Bytes 8 outputs; 8-bit UDB PWM 1374 91 940 93 968 93 8 outputs; 9- or 10-bit UDB PWM 1500 115 1004 117 1056 117 16 outputs; 8-bit UDB PWM 1602 180 1100 181 1176 181 24 outputs; 8-bit UDB PWM 1810 270 N/A N/A 1388 271 8 outputs; 8-bit fixed-function PWM N/A N/A 2356 93 N/A N/A 8 outputs; 10-bit fixed-function PWM N/A N/A 2460 117 N/A N/A Functional Description The component is built from an array of 8-bit to 10-bit PWMs. The PWM outputs from PSoC are RC filtered to generate analog control voltages that connect to the “adjust”, “sense” or “feedback” point of adjustable power converters through a summing resistor. Figure 1 and Figure 2 show the basic circuit model for trimming a DC / DC regulator with a negative or positive feedback control loop, respectively. An increase in PWM duty cycle increases the analog control voltage. This results in a decrease (negative) or increase (positive) of power converter output voltage. Conversely, a decrease in PWM duty cycle decreases the analog control voltage. This results in an increase (negative) or decrease (positive) of power converter output voltage. Document Number: 002-10607 Rev. ** Page 21 of 27 Trim and Margin PSoC® Creator™ Component Datasheet Figure 1. Trimming DC/DC Converter with a Negative Feedback Control Loop Figure 2. Trimming DC/DC Converter with a Positive Feedback Control Loop The duty cycle adjustments are based on two different methods depending on the Controller method parameter: Incremental Controller The duty cycle is incremented or decremented, depending on whether the desired voltage is higher or lower than the measured voltage, as well as the type of feedback the converter supports. Page 22 of 27 Document Number: 002-10607 Rev. ** PSoC® Creator™ Component Datasheet Trim and Margin Integral Controller The integral controller follows the following equations: Negative feedback: 𝐷𝑢𝑡𝑦 𝐶𝑦𝑐𝑙𝑒[𝑛] = 𝐾𝑖 ∗ 𝑒𝑟𝑟𝑜𝑟 ∗ 𝑐𝑡 − 𝐷𝑢𝑡𝑦𝐶𝑦𝑐𝑙𝑒[𝑛 − 1] Positive feedback: 𝐷𝑢𝑡𝑦 𝐶𝑦𝑐𝑙𝑒[𝑛] = 𝐾𝑖 ∗ 𝑒𝑟𝑟𝑜𝑟 ∗ 𝑐𝑡 + 𝐷𝑢𝑡𝑦𝐶𝑦𝑐𝑙𝑒[𝑛 − 1] Where: 𝑒𝑟𝑟𝑜𝑟 = 𝐷𝑒𝑠𝑖𝑟𝑒𝑑 𝑉𝑜𝑙𝑡𝑎𝑔𝑒 − 𝐴𝑐𝑡𝑢𝑎𝑙 𝑉𝑜𝑙𝑡𝑎𝑔𝑒 The ct is the Control sample time provided in the GUI. The integral gain Ki is calculated as: 2𝑛 1 𝐾𝑖 = 𝑤𝑐𝑟 ( ) × 𝜏 × √𝑤𝑐𝑟 2 + 2 𝑉𝑀𝐴𝑋 − 𝑉𝑀𝐼𝑁 𝜏 Where n is the PWM resolution and 𝜏 is the time constant for the RC circuit, which is calculated as: 𝜏 = 𝑅4 × 𝐶1 And 𝑤𝑐𝑟 is the crossover frequency, which is calculated as: 𝑤𝑐𝑟 = 2𝜋 1 × 𝑐𝑡 10 Or 1 1 × tan(10°) × 𝜏 3 The lowest frequency out of the two equations is the one used in the Ki equation. 𝑤𝑐𝑟 = This block needs to comprehend the adjust or feedback control voltage level and the values of feedback resistors R1 and R2 required to achieve nominal output voltage in order to power up in a good configuration without adversely affecting the power converter outputs. This information can be found in the power converter datasheet. The resistor R3 and the RC filter values R4 and C1 are recommended to the user based on the parameter settings in the hardware tab of the configuration dialog. Clock Selection There is no internal clock in this component. You must attach a clock source. This component operates from a single clock connected to the component. Document Number: 002-10607 Rev. ** Page 23 of 27 PSoC® Creator™ Component Datasheet Trim and Margin Industry Standards MISRA Compliance This section describes the MISRA-C:2004 compliance and deviations for the component. There are two types of deviations defined: project deviations – deviations that are applicable for all PSoC Creator components specific deviations – deviations that are applicable only for this component This section provides information on component-specific deviations. Project deviations are described in the MISRA Compliance section of the System Reference Guide along with information on the MISRA compliance verification environment. The Trim and Margin component has the following specific deviations: MISRA-C: 2004 Rule 19.7 Rule Class (Required/Advisory) A Rule Description Description of Deviation(s) A function should be used in Deviated since function-like macros preference to a function-like macro. are used to allow more efficient code. This component has the following embedded component: Control Register. Refer to the corresponding component datasheet for information on their MISRA compliance and specific deviations. Resources On PSoC 4, the Trim and Margin component resource usage is mostly dependent on the implementation type of the internal PWMs. That is, the PWM can either be implemented in the UDB array or use the fixed-function TCPWM block. On PSoC 3 and PSoC 5LP, there are no options for the implementation type of the PWM. The component is placed throughout the UDB array. Configuration N outputs; 8-bit UDB PWM N outputs; 9- or 10-bit UDB PWM 1 Resource Type Datapath Cells Macrocells Status Cells Control Cells TCPWM Interrupts CEIL(N/2) [1] 1 – 1 – – N 1 – 1 – – CEIL(x) gives the smallest integer not less than x. Page 24 of 27 Document Number: 002-10607 Rev. ** PSoC® Creator™ Component Datasheet Trim and Margin Configuration Resource Type Datapath Cells Macrocells Status Cells Control Cells TCPWM Interrupts – – – 1 [2] N – N outputs; 8-, 9- or 10-bit fixed-function PWM DC and AC Electrical Characteristics Specifications are valid for –40 °C ≤ TA ≤ 85 °C and TJ ≤ 100 °C, except where noted. Specifications are valid for 1.71 V to 5.5 V, except where noted. DC Characteristics Min Typ[3] Max Units N outputs; 8-bit UDB PWM – N ˣ 2.5 – µA/MHz N outputs; 9- or 10-bit UDB PWM – Nˣ4 – µA/MHz N outputs; 8-, 9- or 10-bit fixed-function PWM – – N ˣ ITCPWM [4] µA Min Typ Max[5] Units 8-bit UDB PWM – – 55 MHz 9- or 10-bit UDB PWM – – 50 MHz 8-, 9- or 10-bit fixed-function PWM – – FCPU [6] Parameter IDD Description Component current consumption AC Characteristics Parameter fCLOCK Description Component clock frequency 2 For fixed-function PWM implementation, a control register is used only if an alert pin is present / used in the design. 3 Device IO and clock distribution current not included. The values are at 25 °C. 4 ITCPMW – current consumption of the TCPWM block. Refer to the Timer Counter PWM component datasheet for details on its current consumption. 5 The values provide a maximum safe operating frequency of the component. The component may run at higher clock frequencies, at which point you will need to validate the timing requirements with STA results. 6 Maximum CPU frequency for the target PSoC device. Document Number: 002-10607 Rev. ** Page 25 of 27 PSoC® Creator™ Component Datasheet Trim and Margin Component Changes This section lists the major changes in the component from the previous version. Version 3.0 2.0 Description of Changes Reason for Changes / Impact Added support for PSoC 4 device family. New device support. Implemented an integral control for actively controlled trim operation. The active trimming supports either incremental or integral control based on the Controller method parameter. Added support for power converters with positive feedback control loop. New circuit model is provided to support the power converters with positive feedback. The Feedback parameter is configured per power converter. Datasheet update. To reflect changes made in version 3.0. Corrected erratum ID 152757 (The Trim and Using a converter that deviated from this model Margin component conforms to a specific model could result in voltage overshoot or undershoot when calculating the duty cycles required to when margining. achieve desired voltage targets. That model is appropriate for the linear regulator as configured in the Cypress CY8CKIT-035 development kit, but is not appropriate for some other configurations or for switching power supplies.) A new method was developed to input the trim and margin parameters. Updated the Configure dialog to better reflect an external RC circuit configuration. Note Export/Import of CSV file format is no longer supported with this change. You can import your previously saved configuration to v1.30 and then update to the most recent component version. Added SetTrimCycleCount() API to adjust the active trim cycle. The API allows to speed up or slow down the active trimming. Added SetNominalVoltage() and GetNominalVoltage() APIs to adjust the nominal voltage. Usability enhancement. Renamed the following functions: For backward compatibility, all old names are preserved through compatibility macros but not recommended to use in new designs. SetNominal() -> Nominal() SetPreRun() -> PreRun() SetStartup() -> Startup() SetStartupPreRun() -> StartupRreRun() Datasheets edits and corrections. To reflect changes made in v2.0. Note The errata section was removed from this datasheet. 1.30.a Added Component Errata section. Document known problems in the component. 1.30 Fixed a defect in the TrimMargin_ConvertVoltageToDutyCycle() API. The API did not work correctly for PSoC 3. Minor datasheet corrections. Page 26 of 27 Document Number: 002-10607 Rev. ** PSoC® Creator™ Component Datasheet Version Description of Changes Trim and Margin Reason for Changes / Impact 1.20.a Edited datasheet to remove references to PSoC 5. PSoC 5 has been replaced by the PSoC 5LP. 1.20 Added MISRA Compliance section. The component has specific deviations described. Added PWM frequency field in the customizer Hardware tab. Usability enhancement. Added Load / Save configuration commands. Customizer updated with calculated values for Vmax, Vmin, R2, R3, R4, Max Ripple, C1, Nominal PWM. Usability enhancement. Added Startup voltage column in the customizer Voltages tab and following APIs to set up these voltages: TrimMargin_SetStartup(), TrimMargin_SetStartupPreRun(). Ability to start up to the custom voltage. Added following APIs to allow converting voltage to PWM duty cycles: Provide support for trimming to an arbitrary voltage. TrimMargin_ConvertVoltageToDutyCycle() TrimMargin_ConvertVoltageToPreRunDutyCycle() 1.10 1.0 Updated Macro names and configuration. Import All and Export All functions import/export all tables to/from one single CSV file, instead of several files. Changed CSV format to use "," as the separator. This makes it easier for users to manually edit the component configuration. Trim/Margin Resolution column added to the Hardware tab. This parameter indicates how much the power converter output voltage will change as a result of a change in duty cycle of one step. Initial version of the component. © Cypress Semiconductor Corporation, 2016. The information contained herein is subject to change without notice. Cypress Semiconductor Corporation assumes no responsibility for the use of any circuitry other than circuitry embodied in a Cypress product. Nor does it convey or imply any license under patent or other rights. Cypress products are not warranted nor intended to be used for medical, life support, life saving, critical control, or safety applications, unless pursuant to an express written agreement with Cypress. Furthermore, Cypress does not authorize its products for use as critical components in life-support systems where a malfunction or failure may reasonably be expected to result in significant injury to the user. The inclusion of Cypress products in lifesupport systems application implies that the manufacturer assumes all risk of such use and in doing so indemnifies Cypress against all charges. PSoC® is a registered trademark, and PSoC Creator™ and Programmable System-on-Chip™ are trademarks of Cypress Semiconductor Corp. All other trademarks or registered trademarks referenced herein are property of the respective corporations. Any Source Code (software and/or firmware) is owned by Cypress Semiconductor Corporation (Cypress) and is protected by and subject to worldwide patent protection (United States and foreign), United States copyright laws and international treaty provisions. Cypress hereby grants to licensee a personal, non-exclusive, non-transferable license to copy, use, modify, create derivative works of, and compile the Cypress Source Code and derivative works for the sole purpose of creating custom software and or firmware in support of licensee product to be used only in conjunction with a Cypress integrated circuit as specified in the applicable agreement. Any reproduction, modification, translation, compilation, or representation of this Source Code except as specified above is prohibited without the express written permission of Cypress. Disclaimer: CYPRESS MAKES NO WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, WITH REGARD TO THIS MATERIAL, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Cypress reserves the right to make changes without further notice to the materials described herein. Cypress does not assume any liability arising out of the application or use of any product or circuit described herein. Cypress does not authorize its products for use as critical components in lifesupport systems where a malfunction or failure may reasonably be expected to result in significant injury to the user. The inclusion of Cypress’ product in a life-support systems application implies that the manufacturer assumes all risk of such use and in doing so indemnifies Cypress against all charges. Use may be limited by and subject to the applicable Cypress software license agreement. Document Number: 002-10607 Rev. ** Page 27 of 27