This page provides the details and guidance to the SoC Vendors on how to adopt RDK. The porting procedure and the procedures for SoC to get an RDK based Platform up and running is also described in detail.

Before You Begin


RDK License

SoC vendors are advised to get into an agreement with RDK Management LLC to obtain the free license so as to use the complete RDK Code base in their platform. More details about license is available at https://rdkcentral.com/licenses/ . Please email info@rdkcentral.com if you have additional questions about licenses or membership


Bringing up RDK by SoC - Approach



This section will detail the recommended step by step procedure of adopting RDK by a SoC


Product Specifications


The first step to get a fully functional product is to define the product features and see if they meet the standard requirements. See here to know what are all the features available in RDK-V and can implement based on your requirement. SoC can use this as a guide while engineering the RDK SoC platform.

RDKM On-boarding


RDKM provides a collaboration zone facility for SoCs to facilitate easier engineering of RDK based devices. The collaboration zone will help SoCs to work with OEMs, RDKM and any 3rd party along with a common space to develop & integrate, manage and verify the device. The zone includes facilities for code management, a confluence based RDK Wiki for knowledge management & sharing, a JIRA for tracking activity progress, issues as well as to manage the activities, a test setup to validate devices. The access restrictions implemented will help the collaboration zone to be accessible only for the authorized personnel thereby guarding any sensitive information related to SoC/OEM/Third party.

Roles & Responsibilities

A table explaining the roles & responsibilities of SoC & RDKM in the collaboration zone is given below:


#

Activity

Owner

Remarks

1

RDKM

RDKM will setup Collaboration space, access restrictions

2

JIRA Project creation

SoC

JIRA project. SoC will be the owner for the JIRA project

3

SoC  meta-layer creation in collaboration zone

SoC/RDKM

RDKM will create the space and SoC push the code changes

4

Device specific HAL repo creation

SoC

Create necessary device specific HAL implementation for porting RDK into Accelerator

5

Share SoC SDK Artifacts

SoC

Which SDK version to be used. RDKM will support the integration with SoC libraries

6

Manifest creation

SoC

Manifest for building the accelerator

7

UI/UX(only for RDK licensee)

RDKM/SoC

Comes with pre-integrated UI’s, SoC and RDKM will discuss on the default UI

8

Create RDK build from CMF GIT

SoC/ RDKM

Both teams work together to build Accelerator from CMF

9

Provide Devices to RDKM team

SoC


10

Device flashing instructions / recovery mechanisms

SoC

SoC should share the device flashing instruction

11

Sanity, Functionality Testing & automation tests

RDKM/SoC

RDK Certification Suite

12

Monthly release & tagging

SoC

Monthly tagging and release with stakeholders along with test results

It is expected that SoC has already obtained a license to work with RDKM (If not, SoC can send a mail to support@rdkcentral.com to start off with the discussions).

With this user account an INFRA ticket can be raised at https://jira.rdkcentral.com to create a collaboration repo. The ticket should contain the details for:

  • Location of collaboration zone
  • Collaboration zone access groups/members

SoC users can sign up at https://wiki.rdkcentral.com/signup.action to create a user account in RDK. For any issues faced, a mail can be sent to support@rdkcentral.com

An INFRA ticket needs to be raised at https://jira.rdkcentral.com with the below details:

  • Collaboration zone/repo name
  • User name and the mail id's of the members to whom the access is needed
  • SoC collaboration zone/repo owner name

For any issues faced, a mail can be sent to support@rdkcentral.com

An INFRA ticket needs to be raised at https://jira.rdkcentral.com to create a JIRA project for SoC. Once approvals are received along with required access restrictions, the project will be created. For any issues faced, a mail can be sent to support@rdkcentral.com

To get a Git repository a request needs to be raised to CMF team using the CMFSUPPORT ticket at https://jira.rdkcentral.com. Once approvals are received along with required access restrictions, the repo will be created. Any changes in merge permissions can be requested in same ticket. For creating any specific branches in the repo, another ticket in the same CMFSUPPORT can be raised. For any issues faced, a mail can be sent to support@rdkcentral.com

Once the git repo is created, it can be accessed at https://code.rdkcentral.com

An INFRA ticket needs to be raised at https://jira.rdkcentral.com to get access to SDK Artifacts. Once approvals are received along with required access restrictions, the access should be in place. For any issues faced, a mail can be sent to support@rdkcentral.com

Product Engineering


Once the product features are decided, the device engineering can be started. SoC needs to decide on the hardware layout that incorporates components to the target board. Device will be categorized as Low Profile and High Profile device based on the hardware capabilities. In a low profile device 4k support might be optional but it is expected to have 4k support in high profile device.

Sample Reference Flash Layout (Optional) :

Reference Flash Layout

  flash0.macadr  EMMC flash Data :  1024B
  flash0.nvram  EMMC flash Data : 64KB
  flash0.recovery  EMMC flash Data : 256MB
  flash0.vendor  EMMC flash Data : 128MB
  flash0.kernel_a  EMMC flash Data : 128MB
  flash0.kernel_b  EMMC flash Data : 128MB
  flash0.rootfs_a  EMMC flash Data : 1024MB
  flash0.rootfs_b  EMMC flash Data : 1024MB
  flash0.rootdata  EMMC flash Data : 2048MB
  flash0.rsvd  EMMC flash Data : 10174MB

SoC Platform Firmware



SoC can make use of the below details available to start developing a Yocto build to engineer the device firmware builds based on RDK Yocto build setup.

Yocto Manifests

Yocto based RDK builds are flexible enough to easily accommodate SoC / OEM / MSO / third party changes. The starting point for the Yocto builds are a manifest file. The manifest file is an xml file that contains details of the different open embedded Yocto build layers, meta layers , rdk as well as open source components that needs to be fetched during initial stages ( than during bitbake time ) as well as the URL locations from where the data can be pulled. A set of sample manifests that can be used as a template for developing SoC specific manifests are given below


#

File

Remarks

1

Device Specific Manifest

This is the starting point of the build and is specific to a device/board . If the SoC has only one  target device /board, still it is recommended to maintain a different manifest for SoC for keeping it future-proof. Usually it contains references to other manifest files which will be having  specific set of repos

2

SoC manifest

This manifest contains meta layer details of SoC and , optionally, some SoC specific repos

3

OE layers manifest

This manifest has details of the basic Yocto Open Embedded layers

4

RDK-V manifest

This manifest can contain meta layers specific to RDK & RDK-V and , for EXTERNALSRC cases, the RDK & RDK-V component repo details too. It might be supplemented with a conf file too

5

Third Party Apps manifest

This manifest can contain meta layers related to Premium streaming applications which are chosen by SoC


The default manifest repo in RDKM Git is at https://code.rdkcentral.com/r/#/c/manifests/ . SoC can use the 'collaboration' sub section in this repo to add their platform specific manifests which will be under collaboration zone restrictions . The location will be https://code.rdkcentral.com/r/collaboration/SoC/<platform>/<platform-manifests>


For more details on getting RDK-V ported to an OEM device, please refer the links RDK-V SoC Specific Porting and Guideline for SoC and OEM Vendors

SoC/OEM meta-layer creation

To match the layered structure of Yocto builds, a SoC specific layer is used to include SoC changes and additions. Use the yocto-layer create sub-command to create a new general layer.

$ yocto-layer create mylayer

There shall be separate device (machine) configuration file (.conf) for each device for the particular chip family for which the layer is intended for. The general naming terminology for SoC layer is meta-rdk-SoC-<SoC name>

The device (machine) configuration file shall include corresponding include (.inc) file to get machine configuration details.


Adding the Machine Configuration File for the new SoC

Each meta-* layer should have a conf folder containing the machine configuration we can select during 'source setup-environment' . Optionally it can also have a class/classes folder for keeping information that is useful to share between metadata files.

To add a machine configuration, you need to add a .conf file with details of the device being added to the conf/machine/ file. In the machine conf file the basic machine configuration should be defined.

SoC can have several meta-rdk-<chip-set> layers containing chip specific implementation.

Generally conf file name will be SoC name. If both OEM and SoC are present then machine configuration should be coming from master i.e. OEM . It means whatever image that gets created comes from meta-rdk-oem


The most important variables to set in this file are as follows :

  • Include .inc's ,basically these inc's are from SoC layer and these .inc's are platform dependent.
  • Fill the MACHINEOVERRIDES (Eg: If it is media client, give client name)
MACHINEOVERRIDES=" "
  • For particular SoC build , if they are overwriting any kernel version or gcc compiler version or whatever preferred should be defined in machine conf file.

For SoC, The most important variables to set in this conf file are as follows : 

TARGET_ARCH (e.g. "arm")
PREFERRED_PROVIDER_virtual/kernel (Eg:"linux-<chip set name>")
MACHINE_FEATURES (e.g. "apm screen wifi")
KERNEL_IMAGETYPE (e.g. "uImage") 
IMAGE_FSTYPES (e.g. "tar.gz ext4")


Basic configuration of building kernel

Standard meta-rdk/recipe-core/images will have different kinds of images which one can use and build.

This recipe-core/images will have bbappend or main image name. If  meta-rdk is used( i.e. meta-rdk image ) then bbappend of that image client is required

For example,

<image name>.bbappend

(info) Define "bbappend of images" and "conf file" as required.


SoC meta-layer recipes

Generally SoC meta-layer (Eg: meta-<SoC name>) will have following recipes

SoC meta layer recipes-
=========================================
recipes-bsp
recipes-core
recipes-kernel
recipes-connectivity
recipes-graphics
recipes-support etc

The structure of meta-<SoC name>/recipes-support/<SoC-img-packer>/ is as follows -
=========================================
$ls

<SoC-img-packer-native>.bb         files

TDK and RDK Certification Suite Package


RDKM offers an in-house Test & certification suite that facilitates SoCs to get their IP Set-top product certified as RDK Compliant device.

Certification program includes testing which validates the RDK stack on the device with defined test suite called as RDK Certification Test Suite. It is mandatory to go through this program in order to brand user's platform as RDK compliant product.

Certification suite is available at RDK IP Set-top Product Certification(only for RDK licensee) and for TDK test app please refer TDK-V Documentation(only for RDK licensee).

SDK Releases


Once the RDK bring-up in SoC is completed, the vendor needs to plan on the delivery of the software to OEM vendors. This usually happens in 2 ways:

HAL + SDK binary

In this approach will make use of the RDK Artifactory server. Artifactory server is a Repository Manager that functions as a single access point organizing all the binary resources including proprietary libraries, remote artifacts and other 3rd party resources. It is a secure and restricted server, only collaboration members will have access to this server. SoC secure information like secure components such as PlayReady, widevine and Dolby libraries etc. can be hosted in Artifactory server.

SoC vendor can define a HAL layer, share the source of HAL & yocto meta layer that can be stored in RDK CMF Git repository (which will be shared only  to authorized OEM vendors who will work in collaboration with the SoC vendor), share the SDK binary that can be stored in RDK Artifactory (which will be shared only to authorized OEM vendors who will work in collaboration with the SoC vendor) and then publish necessary documentation on how to build the SoC SDK. SoC vendor can use the git/ Artifactory for periodic updated (for releases) or for bug fixes. All the source code, binary and documentation will be strictly access restricted and access will be allowed only for authorized personnel by SoC vendor.

Artifactory server can be accessed by adding the Artifactory details and login credentials in the .netrc file, just like it is done for normal git repositories. A sample is given below:

machine your.artifactory.host
login YOUR_ARTIFACTORY_USERNAME
password YOUR_PASSWORD_OR_KEY_OR_TOKEN

Complete source code

In this approach, SoC vendor can define a HAL layer, share the source of HAL , yocto meta layer and SDK source code that can be stored in RDK CMF Git repository( which will be shared only  to authorized OEM vendors who will work in collaboration with the SoC vendor )  and then publish necessary documentation on how to build the SoC SDK. SoC vendor can use the git for periodic updated ( for releases ) or for bug fixes. All the source code and documentation will be strictly access restricted and access will be allowed only for authorized personnel by SoC vendor.


For both approaches, the RDKM collaboration zone will be used with strict access restrictions.


Collaboration with OEMs


After a successful bring up of RDK on SoC platform, the next step will be to allow OEMs to work with SoCs to get a device based on the SoC platform. RDKM offers collaboration space for SoCs which would help SoCs to collaborate with OEM and RDK teams (as well as any 3rd party) in their journey to engineer a successful RDK product. RDKM collaboration zone includes features like (but not limited to) CMF facility to maintain build manifests as well as SoC/OEM specific code, SoC SDK artifact storage facility, JIRA & RDK Wiki spaces, integration with Test & Certification suites, monthly & release tagging etc.

Please refer RDKM On-boarding for more details on facilities available for SoCs and OEMs as part of collaboration zone . In short, it will include:

  • Access restricted Git repositories and Artifactory servers
  • Access restricted Confluence and JIRA spaces for Management and Documentation
  • Access to RDKM support as well as extended documentation
  • Access to test & certification support 


RDK porting guide to SoC vendors



The aim of this SoC porting guide is to guide SoC Vendors on how to port RDK to their platforms.



Step 1 : Get a board with Linux and drivers

RDK is based on Yocto Linux. Prior to porting RDK on a SoC , the precondition is to have the SoC platform running on Linux. The Linux version can be a SoC specific one with kernal hardening and other OS optimizations specific to SoC, as RDK could easily run on top of vendor specific Linux. SoC should also provide drivers for the other peripherals in SoC platform, like WiFi, so that the unit can work independently and completely from a SoC point of view.

Step 2 : Move the build to Yocto, compare it to supported Yocto version of RDK

Once SoC vendor is ready with an own port of Linux + drivers for the SoC platform, it is time to migrate the platform to Yocto based builds. If the SoC is already having a Yocto based Linux, this step can be skipped. The current Yocto versions supported are Yocto 3.1- Dunfell ( preferred ) as well as Yocto 2.2- Morty ( soon to be deprecated )

Yocto 3.1 Upgradation support the following:

  • Version upgrades for bitbake, GStreamer and other OE components

  • Linux kernel 5.4 or above

  • Extensible SDK

Each component in RDK is a standalone repository with its own individual build tools producing a library or set of binaries. When OE layers are upgraded to the newer versions, necessary changes need to be made in the RDK Yocto meta layers which use these components, to avoid build failures.

Step 3 : Compare and verify the compiler flags used in RDK and in platform to avoid issues

This is an important step while porting RDK to a new SoC platform. RDK Linux is built with considering particular build flags/features in target platform( For example, RDK considers hardware floating point in platform where as some platforms are on software based floating point ). SoC vendor need to analyze such flags in RDK and then make a comparison with the existing SoC platform Linux to ensure compatibility or to understand the required modifications in RDK code so as to house the compatibility changes

Specific DISTRO_FEATURES can be added to support build time flag for specific platforms. For example : DISTRO_FEATURES_append = " referencepltfm "

Step 4 : Compare the open source versions used in platform as different versions will cause problems

Depending on the Yocto version, the RDK build will be working with some particular version of Open source components. This might either be a dependency with the Yocto version compatibility as such or with RDK ( functionality or license issues ). If the SoC Linux has some version dependency on particular open source software and, if it conflicts with the version in RDK, vendor needs to make required changes to make the open source version to match the RDK requirements as best as possible, by adding required patches in SoC platform 

Check below layers for all opensourced version packages recipes used in RDK. If multiple recipes with different versions are available, then check for the value of PREFFERED_VERSION_<recipe name> set.

Meta layers : -  meta-openembedded, openembedded-core, meta-rdk-ext, meta-rdk, meta-cmf

Step 5 : Move the RDK recipes to platform Yocto build

For platform specific recipes, keep them in SoC meta layer. While it is a good practice to start afresh with a new manifest for the target platform, manifest file for  a similar featured platform can be used as a starting point too. Check all device specific repos in the reference manifest, and ensure corresponding device repos are created for this new device as needed, and update the manifest with these updated repos

  • Create artifactory repo for the project with appropriate permissions for vendors. This is used for hosting any binaries required for the project

  • Check-in SoC components - tool chain, SDK, kernel, drivers, etc.. to corresponding SoC gerrit repos/ artifactory as applicable

  • Populate meta SoC layer with initial set of changes needed to build kernel, SoC components, etc..

  • If there is any SoC reference board exists, create corresponding machine configuration in SoC layer, and create a image target to be able to build final image for the reference board. This layer should be separated out with in meta SoC layer from other common SoC, common chip sub layers which will be usually used by meta oem layer as well.

  • Populate meta oem layer with machine configuration and other bare minimum changes required to generate a target image for OEM board.

  • machine configuration can be updated with "NEEDED_BSPLAYERS" field to include required SoC, OEM layers in the build

  • Any unwanted recipes during early stage of bring up can be masked using BBMASK, if needed.

Step 6 : Get a successful build

Add platform specific main recipe to create image.


HAL implementation by SoC


Device Settings

Device settings component is having a HAL interface to control device specific peripherals such as video port, audio port and display and front panel. 

More details on HAL interface can be found here: Device Settings HAL Types & Public API DTCP HAL Interfaces.

DTCP

Integrates the SoC provided DTCP library with DTCP/IP manager Interface implementation which manages source/sink DTCP/IP sessions and performs the encryption/decryption.

HAL Interface specification: DTCP HAL Interfaces

tr69hostif

Contains SoC specific MOCA libraries, headers and MOCA profile codes.

API Details: TR69 Host Interface Handler

For more details on tr69hostif, please refer: tr69hostif

gst-plugins-rdk /qamtunersrc

qamtunersrc is a push based gstreamer source plugin which tunes to the given service and provides the SPTS data.

  • Manages tuner and demux
  • Filters PIDs required for SPTS
  • Output SPTS as gstreamer buffer
Properties
  1. Modulation:
  2. Frequency: frequency to tune in KHZ
  3. Tunerid: Tuner Handle

Depends on platform specific libraries for tune, filtering, and pod functionalities.

gst-plugins-SoC /playersinkbin

Playersinkbin is a gstreamer bin element consisting of demux, decoder and sink elements. A template file gstplayersinkbin.c.template and gstplayersinkbin.h.template are provided as a reference for SoC implementation. SoC has to add details of platform specific plugins and implement the required properties expected out of them.

hdmicec

SDK Vendors should implement CEC driver interface API as specified in hdmi_cec_driver.h

HAL Interface Specificcation: HDMI-CEC HAL APIs specification

iarmmgrs

Power, IR and DeepSleep modules are having SoC dependency. APIs are specified in plat_power.h, plat_ir.h and deepSleepMgr.h

More details about APIs can be found here

westeros-SoC

Contains functions for creating and handling native eglwindow. HAL APIs are specified in westeros-gl.h

Wi-Fi (Client)

Wi-Fi Client HAL provides an interface (data structures and API) to interact with underlying Wi-Fi driver and enabling the client to be connected with an Access Point.

HAL APIs are specified in wifi_client_hal.h. Doxygen Link: Wifi HAL API Specification

Provisioning - iCrypto

Set of Cryptographic APIs Implementation, can be used to achieve all type of Cryptographic requirements from Premium App.

Graphics - westeros backend

Media Pipeline Backend layer is a module in device layer which glues the media pipeline capabilities of the device to that of the IgnitionX.

Input key handling

As part of integrating Premium Apps as a native application on the RDK stack, the Premium Apps Video Porting (PVP) Layer needs to be implemented. The PVP Layer consists of the following modules:

  • Ignition Device Layer
    • Common
    • Display
    • Input
    • TTS
    • Secure Storage
    • Message Bus
  • Device Properties Provider
  • Media Pipeline Backend
  • PlayReady DRM

Media Playback - gstreamer

Abstraction layer for third-party applications to get specific GStreamer values from the SoC pipeline.

DRM (playready, widevine, TEE, SVP etc.)

Amazon assets are encrypted using Microsoft PlayReady. A robust implementation of the PlayReady must be provided for porting kit to decrypt assets.

TTS

Text-to-speech converts text into spoken voice output to help customers navigate the Prime Video application without seeing the screen. Text-to-speech is mandatory for the US region and optional in other regions.



  • No labels