1. Goals

  • Turn an MSP430 devboard into a ShortSquawker.

https://agnd.net/valpo/422/lab3.html

  • Generate an abstract representation of the ShortSquawker application by sketching its actions and requirements.

2. Architecture

It may seem that the best way to port ShortSquawker to the MSP430 is to:

  • Copy the existing single-file’s code into Code Composer Studio.

  • Click the Build button.

    • "Fix" each compilation error.

    • Repeat until there are no errors.

  • Upload to the board

    • Attach signals to pins.

    • Attach oscilloscope probe(s) to output pins.

    • Pray that the signals are "as expected".

    • Go back to the previous step.

  • Weep.

Stated this way, it should be obvious that this is a bad idea. What should you do, then?

2.1. Diagram the application

What actions does the code (need to) do?

What tasks are happening "at the same time" in the application?

List out these tasks:

-> do you notice that there are several tasks ?

Click to reveal after making your own list

  • Read user button and take appropriate action (state machine!).

  • Read input voltage with ADC.

  • Compute the next output sample’s duty cycle value. (Superposition of multiple sine waves).

  • Update the PWM output’s duty cycle at the correct time interval.

  • That debug_value(uint16_t) function.

You must have an overall mental model of what is happening in the code and (mostly) why. How else is it even possible to look at the code and make any sense of it?

For each of the tasks that the code does, collect some properties about each, such as:

  • What information does that task use as inputs?

  • What hardware does each task access or interact with?

    • This is a candidate for HAL code (defined later)

  • When, or how often does each task need to run?

    • Is there a deadline when the task needs to be finished by?

    • Which specific part of the task actually has the timing constraint? (Not every instruction participates in the input or output sample rate effect)

  • What information is communicated between tasks?

    • Where and when does the variable get set.

    • When is the variable used.

This information is extracted from a combination of the code as-received and the design documentation (https://agnd.net/valpo/422/shortsquawker-1.html)

All of this work and diagramming needs to happen before you touch actual code. It is pointless to write code when you don’t know what it should specifically do!

2.2. HAL: Separate the platform dependence

Across several assignments you have been asked to create C code that is "platform independent", meaning that the same .c file can be used for different MCUs without modification.

This requires a "hardware abstraction layer" (HAL) that does include all of the hardware-specific mechanics of interacting with a particular platform. Such code is where port and pin names are named. Your application code never uses hard-coded port names, because this prevents that source file from being usable for other platforms.

2.3. Deliverable

70% of this lab’s work is to generate as complete of a set of diagrams and documentation as you can about the ShortSquawker application. It is nearly impossible to port it to the MSP430 without doing so!

  • The design page ShortSquawker has some of this information.

  • This documentation has both higher-level block diagramming, and extracts out the parts of the design that are dependent on the specific hardware into functional blocks that can be implemented on any capable hardware.

A programmer familiar with a specific platform (not AVR) should be able to write the code for making a ShortSquawker using a particular processor.

You will have, as example:

  • Block diagram showing the tasks and how they interact with each other.

  • Timing diagram and table describing when each task runs, including the conditions that trigger them as necessary.

  • Each task will have a segment of documentation that collects this information

    • Description of what the task does

    • Its inputs or triggering conditions

    • What effects the code has on the system (updating global-type variables, changing hardware state/pins, controlling the settings for a certain peripheral, etc.)

3. CodeComposer Studio project

Mixing C and asm in the same project.

  • Start a new CCS project

ccs new project
ccs build settings lst

  • The first "Keep the generated assembly" will leave an .asm file for each of your .c source files.

  • The second "Generate listing file" will leave a .lst file with extra information alongside the assembly code, similar to the .lst generated with the AVR-GCC tools.

I placed the entire ShortSquawker C code into squawker.c in the project, unmodified, and built the project. The output files will show up under the Debug folder in the Project Explorer.

  • The "Debug" folder is named so because it is the default (build) Configuration

ccs project explorer

3.1. How to mix C and Assembly

Study the table of contents for

Match the Examples in the ZIP archive with this PDF.

(we are using the CCS / TI compiler, and not the IAR compiler)

Match the information in that PDF with the information about how AVR-GCC connects assembly with C. You can find links to that information from the AMA:

https://agnd.net/valpo/422/ama-1.html#_calling_assembly_from_c

Compile the Examples and check the generated .asm and .lst files to match how the system connects the assembly function calls into the complete application.