The lookup service makes API available to the user application to invoke. This section describes the usage of this API.
Finding a Device by Name The MicoGetDevice function shown in
Figure 62 enables you to look up a device by name. The device name is case- sensitive. It returns a pointer to the component’s instance-specific information structure.
Since the components are selected and named at the time of platform generation, you should be aware of the component information structure type for the named device, and you are expected to typecast the returned pointer to an appropriate information structure type.
The Mico System Builder (MSB) software only allows you to generate a platform that contains unique names for all of its defined components. In turn, the managed build process also does not permit duplicate component names in a platform. The lookup service works on the assumption that component names in the platform are unique. Only those devices and services that follow the guidelines for developing device drivers are available for device lookup, as discussed in “Modifying Existing Device Drivers” on page 123.
The code example in Figure 63 illustrates how to use the MicoGetDevice function to find a GPIO named “LED” (case-sensitive) in the platform.
Iterating Through a List of Devices For a platform with multiple instances of components, each component instance is registered with the lookup service. As part of registration information, the device driver must provide a device type to which the component instance belongs. The device type enables your application to iterate through all available instances of a given service type or through all component instances that are available for lookup. Figure 62: MicoGetDevice Function Example
/*
* Finds a device (that is registered with a registered * service)
* Arguments:
* const char *Name: pointer to a character string * representing device name (case-sensitive)
* Returns:
* void *: pointer to the looked-up device’s instance-specific information. Will be 0 if no device with matching name is found.
*/
LATTICEMICO RUN-TIME ENVIRONMENT : Run-Time Services
The application must call the MicoGetFirstDev function, as shown in Figure 64.
The first argument is a pointer to the device type name. This pointer can either be a specific named service type or a device type, or it can be a null Figure 63: Using MicoGetDevice Function to Find a GPIO
#include “MicoGPIO.h” #include “LookupSrevices.h” int main(void)
{
/* fetch LED GPIO by name: name is case-sensitive */ MicoGPIOCtx_t *pLED;
pLED = (MicoGPIOCtx_t *)MicoGetDevice(“LED”); if(pLED == 0) {
/* platform does not contain a registered GPIO named “LED” */
printf(“failed to fetch GPIO (LED) instance\r\n”|; return(-1);
}
return(0); }
Figure 64: Using MicoGetFirstDev Function to Iterate Through a List of Devices
/*
* Finds the first device (that is registered) of the specified * type
* Arguments:
* const char *deviceType : points to named device type. If this * pointer is a null pointer, the first context of the * first device in the list of registered devices is * returned, irrespective of the type under which the * device is registered. If a non-null pointer, it must * point to a valid string (case-sensitive).
*
* DevFind_st *FindCtx: pointer to a valid allocation of * DevFind_st that will be referenced by MicGetFirstDev * for future invocations to MicGetNextDev
*
* Returns: *
* void *: pointer to device context (is null if no matching * device is found).
*/
void *MicoGetFitrsdtDev(const char *deviceType, DevfindCtx_t * FindCtx);
LATTICEMICO RUN-TIME ENVIRONMENT : Run-Time Services
If this pointer is not null, LatticeMico32 attempts to find the first registered component instance of that device type. The second argument to this function is a pointer to a valid structure of type DevFindCtx_t. This structure is filled in by MicoGetFirstDev and should not be modified by the application. This function parameter can be used in subsequent calls to MicoGetNextDev to retrieve the next component instance of the desired type. The return value of this function is a void pointer to the device’s instance-specific component information structure. This pointer is null (zero) if no matching registered device is found.
On a successful completion call to MicoGetFirstDev—that is, the returned pointer is not null—the application can then call the MicoGetNextDev function, as shown in Figure 65, to retrieve a pointer to the next matching device’s instance-specific component information structure. This function takes a single parameter, a pointer to the DevFindCtx_t structure type that was provided to the MicoGetFirstDev function call. The values of the structure referenced by this pointer must not be modified by the application. If the LatticeMico lookup service is successful in finding the next matching registered device, it returns a pointer to the matching device’s instance- specific component information structure.
The CFIFlashPrgrmr.c flash programming software template demonstrates usage of the functions previously referenced for iterating through a list of registered devices of a specific type (for example, the CFI flash device type in the example). This flash programming software template is located in the following path:
<install path>\micosystem\utilities\templates\CFIFlashProgrammer