TI CC13xx/CC26xx SimpleLink platform

[tiepettersen]

Hello Contiki-NG community,

I'm an employee at TI who has been working on porting the srf06-cc26xx platform to a unified platform for all CC13xx/CC26xx devices. With the introduction of the new CC13x2/CC26x2 devices, we at TI saw the opportunity to rework the srf06-cc26xx platform to a new platform based on TI's SimpleLink MCU Platform, which is a single, unified software development environment for all of TI's SimpleLink Wireless MCUs.

This new platform, which we simply call SimpleLink, is an umbrella platform for all SimpleLink devices separated by their respective device family. And, the CC13xx/CC26xx device family will be the first SimpleLink family which is part of this SimpleLink platform.

I do not propose for the SimpleLink platform to replace the srf06-cc26xx platform from the get-go. Instead, I propose for both paltform to run in parallel for now. I've been discussing this with @g-oikonomou and we agreed this is a good approach.

Motivation

By integrating the SimpleLink MCU Platform with Contiki you suddenly have access to the entire SimpleLink software development environment, most notably TI drivers. By using the SimpleLink MCU Platform as a foundation for interfacing the device you have essentially created a common ground across all SimpleLink devices in regards of code. This means a device family, e.g. CC13xx/CC26xx, only has to create and maintain a "gluing" layer between Contiki and the SimpleLink MCU Platform, while TI is required to maintain the SimpleLink MCU Platform.

In addition, this also streamlines the support model immensely for TI when it comes to custommer support with Contiki. The current support model for the srf06-cc26xx platform has been quite demanding for TI, both in resources and time, where the challenge has mostly been debugging unknown drivers and RF settings. The new SimpleLink platform allows us to have a known common ground for all software, and streamlines the entire debug process.

Implementation

The SimpleLink platform is essentially a glorified "gluing" layer between the Contiki environment and the SimpleLink MCU Platform environment. For instance, the prop-mode and ieee-mode now interfaces the RF driver from TI drivers, instead of interfacing the custom made rf-core driver.

The SimpleLink MCU Platform provides a bare-metal RTOS called NoRTOS, which runs on a single stack while providing simple RTOS objects, such as Semaphores and Clocks. Contiki system drivers, such as sys/rtimer and sys/clock, uses these RTOS objects for its implementation. Note that this is required for TI drivers to work.

A Core SDK is provided, which is the core software development kit for all SimpleLink SDKs for CC13xx/CC26xx devices. The Core SDK contains all source code for TI drivers and xxware, as well as the NoRTOS kernel. It is provided as a git submodule, just like cc13xxware and cc26xxware. For the SimpleLink platform the Core SDK replaces the need for the cc13xxware and cc26xxware submodules. Core SDK is released under a BSD-3 clause license. A repository of Core SDK for Contiki-NG can be found on my profile, called coresdk_cc13xx_cc26xx.

Advantages

A list of advantages are listed below:

• Support for CC13x2/CC26x2 devices
• Same Makefile syntax for Boards
  • TARGET=simplelink BOARD=launchpad/cc26x2r1
• Integrates the SimpleLink MCU Platform into Contiki-NG
  • TI drivers
  • Up-to-date RF settings
  • Simple RTOS objects with NoRTOS
  • SimpleLink MCU Platform actively maintained by TI
  • Entitled to support from TI regarding any SimpleLink MCU Platform-related issues
• An umbrella platform for all SimpleLink device families
• A common ground between Contiki-NG and TI software
• Streamlines the process of updating Core SDK

Disadvantages

A list of disadvantages are listed below:

• Increase in code size
  • About 10-20 KB increase in Flash
  • About 1-2 KB increase in RAM
• More project configurations are required to reduce code size wrp. TI drivers
• Not tested with TSCH
• Investments in development for srf06-cc26xx may not apply for the SimpleLink platform

Regarding increase in code size, the majority of increase in Flash comes from the added code overhead with TI drivers, RF settings and RF patches. This may cause some issues with the existing examples for CC13x0/CC26x0 because of not enough Flash/RAM, however, this is no issue for CC13x2/CC26x2 with the increased Flash and RAM. Because of this it would be desirable to keep the srf06-cc26xx platform in parallel for those who's already invested in srf06-cc26xx, as well as the added code size bonus.

Ending Note

I'm open for any feedback and critique. The use of an umbrella platform is only a proposal. If you don't see any benefit from having the umbreall platform SimpleLink and instead just have a single definite platform called cc13xx-cc26xx, I'm all ears.

[g-oikonomou]

This is very exciting to see after the discussions we have had. I am traveling at the moment so will not be able to look into it closely for a few days.

Will look at structure etc first chance

[firmwareguru]

This is great - I'll take a look and provide feedback.

[firmwareguru]

I can't seem to build it. These are the problems I've encountered so far:

1. 'boards' command to list boards doesn't work, as in "make TARGET=simplelink boards"
2. Builds fail outright. Example:

gmake TARGET=simplelink BOARD=launchpad/cc1310
using set target 'simplelink'
FIND: Parameter format not correct
FIND: Parameter format not correct
FIND: Parameter format not correct
  CC        c:/fm/test/contiki-ng/arch/cpu/cc13xx-cc26xx/./ccfg-conf.c
In file included from c:\fm\test\contiki-ng\arch\cpu\cc13xx-cc26xx\cc13xx-cc26xx-conf.h:44:0,
                 from ../../arch/platform/simplelink/cc13xx-cc26xx/contiki-conf.h:51,
                 from c:/fm/test/contiki-ng/arch/cpu/cc13xx-cc26xx/./ccfg-conf.c:44:
c:\fm\test\contiki-ng\arch\cpu\cc13xx-cc26xx\cc13xx-cc26xx-def.h:43:37: fatal error: ti/devices/DeviceFamily.h: No such file or directory
compilation terminated.
gmake: *** [obj_simplelink/ccfg-conf.o] Error 1

[tiepettersen]

@firmwareguru, it is the find command failing. Which GNU environment are you using?

[firmwareguru]

@tiepettersen Oh, that's too bad. I'm using Windows with gmake from xdctools. I can build and run the other TI platforms in Contiki and Contiki-ng just fine... Is there a way to make the stuff that the 'find' commands are doing cross-platform?

[tiepettersen]

@firmwareguru, GNU commands provided by XDCTools are very limited, as they don't fully implement the GNU commands. Lots of lacking features. I can look into it, however, I've struggled a lot with XDCTools.

I found out that Git Bash for Windows provides a very solid GNU environment, which works perfectly fine for all platforms. If you have been using CCS to build Contiki, simply update the PATH variable with /bin and /usr/bin paths in the Git Bash installation dir.

[firmwareguru]

@tiepettersen Thanks for the tips. Alright, I'm using the Git Bash environment to build, which has the requisite 'find' command. I copy gmake.exe and srec-cat.exe into the Git\mingw64\bin directory for it to complete a build.

But do note: oddly, the CORE_SDK 'realpath' statement prepends the current working directory to the CORE_SDK variable. As a result, the external include paths are invalid and the build fails with fatal error: ti/devices/DeviceFamily.h: No such file or directory

To solve this, I remove the following from Makefile.cc13xx-cc26xx

# Clean up the path.
CORE_SDK := $(realpath $(CORE_SDK))

And now I can get through a complete build on my Windows machine.
CORE_SDK is already specified properly, I don't think its necessary to run this realpath on it again.
CORE_SDK := $(CONTIKI_CPU)/lib/coresdk_cc13xx_cc26xx

[tiepettersen]

@firmwareguru, interesting. You are correct, it is already specified properly. I'll remove it then.

[firmwareguru]

I've got both hello-world and rpl-udp examples working on two Launchxl-cc1312r1 boards.

I will note that on the startup banner the PANID field is not set in the radio, as shown on the line
[INFO: CC13xx/CC26xx] RF: Channel 26, PANID 0x0000

[INFO: Main      ] Starting Contiki-NG-release/v4.1-405-g49a577c85-dirty 
[INFO: Main      ] - Routing: RPL Lite 
[INFO: Main      ] - Net: sicslowpan 
[INFO: Main      ] - MAC: CSMA 
[INFO: Main      ] - 802.15.4 PANID: 0xabcd 
[INFO: Main      ] - 802.15.4 Default channel: 26 
[INFO: Main      ] Node ID: 24379 
[INFO: Main      ] Link-layer address: 0012.4b00.18a8.5f3b 
[INFO: Main      ] Tentative link-local IPv6 address: fe80::212:4b00:18a8:5f3b 
[INFO: CC13xx/CC26xx] Operating frequency on Sub-1 GHz 
[INFO: CC13xx/CC26xx] RF: Channel 26, PANID 0x0000
[INFO: CC13xx/CC26xx] Node ID: 24379 

The cause of this is that the setting of the PANID is not implemented in the prop-mode driver. Note that a PANID of 0 is just as valid as abcd.

Maybe this is a good time to ask this question: why aren't the sub-GHz 802.15.4g devices also using the ieee-mode driver? Why is IEEE 802.15.4g handled under the prop-mode driver?

[tiepettersen]

I can fix the lack of PANID information for prop-mode.

Now, regarding why there is a prop-mode and ieee-mode driver. It's because the IEEE RF commands are only for 2.4 GHz, not for Sub-1 GHz. IEEE 802.15.4g at Sub-1 GHz is only realized through the Proprietary RF commands, which is why Sub-1 GHz and 2.4 GHz is split between prop-mode and ieee-mode, respectively.

[g-oikonomou]

I can fix the lack of PANID information for prop-mode.

  LOG_INFO(" RF: Channel %d", chan);

  if(NETSTACK_RADIO.get_value(RADIO_PARAM_PAN_ID, &pan) == RADIO_RESULT_OK) {
    LOG_INFO_(", PANID 0x%04X", pan);
  }
  LOG_INFO_("\n");

is what we do in the current platform for prop mode, which does not support PAN ID on the radio.

[g-oikonomou]

While I am trying to find time to look into this closely, I should mention that we do expect all travis tests to pass and also reasonable doxygen documentation before we can merge this.

[g-oikonomou]

This pull modifies files that do not appear related to what the pull is trying to do here. E.g. various top-level Makefiles, files in the native platform, arm and cortex makefiles, files of the current cpu/platform etc.

Such changes need removed from this pull's diff, unless they are strictly required for the proposed functionality. This will make this PR much easier to review.

Such changes can be included as separate pulls if there is a desire to do so.

[g-oikonomou]

@tiepettersen Hi Edvard

This is a very very very complete port indeed so big thanks to you and all your colleagues at TI.

We have a little bit of work to do before we can merge this:

1. Platform/CPU code:

• I am not 100% satisfied with the cpu/cc13xx-cc26xx name. I think it may confuse users. Could we perhaps sprinkle some "simple-link" as part of the name?
• I would expect doxygen to pass without warnings (respective travis test green). The documentation itself seems to be getting generated in the correct place in the modules hierarchy, so that's great.
• Should we remove arch/cpu/cc13xx-cc26xx/dev/startup_cc13xx_cc26xx_iar.c
• Other than that, I am more or less happy with the platform/CPU code and it looks pretty-much merge-worthy to me.

2. Examples

• I will not insist at this stage, but at first glance there appears to be a big big overlap with the existing ones. Perhaps we can merge them into a single directory. Have you had to change many things?
• Added accidentally? examples/platform-specific/simplelink/cc13xx-cc26xx/very-sleepy-demo/very-sleepy-demo.simplelink. Should be removed if not needed.
• I would love to see changes to PLATFORMS_ONLY, PLATFORMS_EXCLUDE etc in various generic example makefiles to signify that this platform is supported/not supported by an example.

3. I would like to see extensions to travis such that it tests the new platform.

4. Changes that are somewhat of a colateral:

There are changes outside the examples/platform/CPU dir.

• There are minor changes here and there that I have tried to capture as review comments (for example in cc.h)

• There seem to be extensive changes to the build system. I cannot see the motivation for those. Are we fixing a bug here? Or are they things that just felt like a good idea? Or are we adding a feature? A combination? In all cases, those need to move to a separate PR with accompanying motivation. They need implemented such that other platforms don't break.

• You appear to have made extensive changes to the GPIO HAL. At the risk of sounding somewhat overprotective about it, I would like to see any such changes moved to a separate pull request and be done in such fashion that they do not break existing platforms.

  • I can see you are proposing introduction of _arch_init(). I am happy with that.
  • I am not satisfied with the changes to data types, we lose the ability to know exactly what the data size is and the change is not motivated. Is this an attempt to match SDK return types?

5. Core SDK:

No comments. We will adopt it under contik-ng/coresdk_cc13xx_cc26xx with a separate pull after merge.

[MartinNPN]

Hello,

to get more RAM, and have no disadvantage it would be a good possibility to implement the VIMS Split Cache mode. It should be supported by TI Simple Link or ?

[tiepettersen]

@g-oikonomou, some questions:

1. I would like to keep arch/cpu/cc13xx-cc26xx/dev/startup_cc13xx_cc26xx_iar.c, as there are a considerable amount of customers who use Contiki with IAR, and therefore makes sense to supply the startup code for IAR.

2. I've removed the platform-specific example directory as per our discussion. Also, PLATFORMS_ONLY, PLATFORMS_EXCLUDE has been updated.

3. Which compile-arm-ports test should I extend?

4. I've updated collateral per your comments. Note that some considerable changes to the arc/cpu/arm/cortex-m/cm4/Makefile.cm4 was required, as it was pretty much hard-coded for nrf52832. But, it should be more generic now and should compile for both platforms.

[tiepettersen]

@MartinNPN, that is definitely doable. However, that it something we can do as a separate PR.

[g-oikonomou]

1: No objection
2: OK
3: Either is fine, no preference
4: Cheers, I'll have a look

[g-oikonomou]

I am happy with this PR.

It needs a little rebase to fix a conflict and to repoint the submodule to contiki-ng/coresdk_cc13xx_cc26xx

The missing includes can go into a separate PR or can stay here. I no longer have a strong feeling about this

[firmwareguru]

This is great. Congrats on getting this done. Now; we need a radio mode other than nullrdc for the cc13x2 platforms. And yes, here it is: #648

[chinacoolge]

@tiepettersen Hi , I had some problems with the project.
When I modify the makefile like this:
TARGET = cc26x0-cc13x0
BOARD = launchpad/cc1310
#CFLAGS += -g
everything works perfectly, but when I changed the TARGET to simplelink, as follows:
TARGET = simplelink
BOARD = launchpad/cc1310
It seems that the CC1310 crashed, which was described HERE

[tiepettersen]

@chinacoolge, this is not the right place to post your issue. The support will continue on the linked E2E post.