NDK Documentation improvement suggestions

Raymond Mack

Hey y'all:

I am doing a lot of NDK work and always start by reading the manuals (SPRU523 SPRU524). We want to be able to assign a static IP to our boards that is stored in non-volatile memory rather than being embedded in the code by xconfig. One can use xconfig to set a static IP, but then it is that value for *all* boards using that code! There is a nice cfgdemo program in the NSP. It has the following lines of code:

//
// ReadConfig()
//
// Read Configuration Info from hCfg Handle
//
static void ReadConfig()
{
    CI_SERVICE_DHCPC dhcpc;
    CI_IPNET          ci_net;
    CI_ROUTE          RT;
    IPN               IP;
    int               i,tmp;

    // Get hostname
    tmp = CfgGetImmediate( 0, CFGTAG_SYSINFO, CFGITEM_DHCP_HOSTNAME, 1,
                           31, (UINT8 *)Hostname);

The comment for the function says it will use hCfg in order to communicate with the configuration subsystem. You will notice that the hCfg position in CfgGetImmediate() is a Zero. One would assume from this example that passing Zero will use the default configuration which is presently active. If that is the case, it is NOT documented in SPRU524H. If that is not the case, how does it work if the handle value is really something other than Zero?

Likewise, SPRU524H does not have any list of tags such as CFGTAG_SYSINFO or CFGITEM_DHCP_HOSTNAME. It is a real pain in the rear end to have to go track down a header file in the source tree and then guess what each of those constants does. A solution for putting all of that possibly changing information in SPRU524 is to create a link to a new document (SPRU999 for instance) that gets hyper-linked into SPRU524.

So, the suggestion is to add a whole lot more meat to Appendix G of SPRU524 including a list of ALL possible parameters for the things you can configure. Also, document why you can use Zero for hCfg rather than calling CfgGetDefault() to retrieve the currently active configuration handle. How does it work? Are there pitfalls? Is there some other (perhaps better) way to hold configuration in non-volatile memory and do the configuration at runtime?

Thanks.

Ray

over 11 years ago

0 Moses Isang over 11 years ago

TI__Expert 8175 points

Ray,

From my understanding, you want to assign static addresses that are not hard-coded in the *.cfg file. Below is C code that shows how you can do this. It's up to your application to read the static IP at runtime from whatever non-volatile memory you choose.

/*use this to get the configuration handle*/
hCfg = CfgGetDefault(…);

And use the returned hCfg in the assigning the IP address as in the code below

/* Static IP Address settings */
char *LocalIPAddr = "10.90.90.3";
char *LocalIPMask = "255.0.0.0";
char *GatewayIP   = "0.0.0.0";

CI_IPNET NA;
CI_ROUTE RT;
        
/* Setup manual IP address */        
bzero(&NA, sizeof(NA));
NA.IPAddr  = inet_addr(LocalIPAddr);
NA.IPMask  = inet_addr(LocalIPMask);
strcpy(NA.Domain, DomainName);        
NA.NetType = 0;
        
CfgAddEntry(hCfg, CFGTAG_IPNET, 1, 0,
                sizeof(CI_IPNET), (UINT8 *)&NA, 0);
        
/*
 *  Add the default gateway. Since it is the default, the
 *  destination address and mask are both zero (we go ahead
 *  and show the assignment for clarity).
 */
        
bzero(&RT, sizeof(RT));        
RT.IPDestAddr = 0;
RT.IPDestMask = 0;
RT.IPGateAddr = inet_addr(GatewayIP);
        
CfgAddEntry(hCfg, CFGTAG_ROUTE, 0, 0,
                sizeof(CI_ROUTE), (UINT8 *)&RT, 0);

Also know that configuration can be done at runtime in C code. Xgconf provides a means for static configuration while modules also have equivalent C API's that can be used in your application at runtime.

Let me know if this helps.

Moses

0 Raymond Mack over 11 years ago in reply to Moses Isang

Expert 1575 points

Moses:

This is the process that I will be using and I expect that it will work OK. It is the process that is indicated by reading the manual.

My suggestion stems from the absence of a description of CFGTAG_IPNET, CI_IPNET, or CI_ROUTE in the NDK manuals (SPRU523 and SPRU524). It is a VERY BIG PAIN to have to go find a header file somewhere in the tree and *maybe* be able to figure out which keys and types to use.

Where did *you* go to find the appropriate data types and configuration keys????

My other suggestion is to not use undocumented features like using "0" for the hCfg parameter in CfgAddEntry as occurs in one of the NSP examples.

These are suggestions aimed at helping improve your documents.

Ray

0 Moses Isang over 11 years ago in reply to Raymond Mack

TI__Expert 8175 points

Raymond,

We agree. We are continually updating the documentation in order to improve it. We just went through an update for the next NDK release, however this suggestion came in too late for that. We will make sure to have the doc updated based on your feedback next time.

I've filed the following bug to ensure this gets fixed in the future.

https://cqweb.ext.ti.com/cqweb/main?command=GenerateMainFrame&service=CQ&schema=SDO-Web&contextid=SDOWP&entityID=SDOCM00111763&entityDefName=IncidentReport&username=readonly&password=readonly

Thanks,

Moses

0 Raymond Mack over 11 years ago in reply to Moses Isang

Expert 1575 points

Moses:

I ran across another way to do the process that you can add to the next version of the documents. At least I don't think I saw this suggestion in SPRU523 or SPRU524. A co-worker ran across something in the forums (it may have even been your suggestion):

1) In the configuration screen for NDK/Global, put in a function name instead of NULL for the NDK startup hook. This occurs before the stack actually gets up and running.

2) In your code, implement the function name you entered for the hook. Change the value of the LocalIPAddress variable to your value from non-volatile memory inside that hook function.

These are two equally valid ways to change the default configuration from that set in the IDE to what a user has stored in nv memory. Using the Cfg functions and keys is useful if you want to do all of the re-configuration in one easy to find and maintain place. Using the hook functions is a good alternative if you don't mind having your re-configuration sprinkled throughout your code.

Ray

Processors

Processors forum

NDK Documentation improvement suggestions