How to

Contents

• 1. How to use CoX Peripheral Library?
  • 1.1 Step of using CoX Peripheral Library?
  • 1.2 How to use GPIO shortpin(PA0) feature?
    • 1.2.1 What is a GPIO shortpin?
    • 1.2.2 When to use the shortpin feature?
    • 1.2.3 How to use the shortpin feature?
  • 1.3 How to use the CoX interrupt feature?
  • 1.4 How to Use the Peripheral?
  • 1.5 Make your code be ported more easily based on CoX
  • 1.6. Code Standard in CoX
    • 1.6.1 Naming
    • 1.6.2 Doxygen
• 2. How to Port CoX to other MCU platforms?

1. How to use CoX Peripheral Library?

1.1 Step of using CoX Peripheral Library?

1. Select the CoX implmentation according to the selected MCU, such as NUC1xx CoX Peripheral Library. copy the libcox, startup to your workdir.
2. Determine the compiler IDE, such as MDK, add startup_rvmdk.s to your project.
3. Define preprocessor symbols to tell the CoX that which compiler you use:
   • gcc - CooCox CoIDE(GCC).
   • ewarm - IAR EWARM.
   • rvmdk - Keil MDK.
4. Define preprocessor symbols xDebug to enable the CoX debug feature, xASSERT to assert some conditions.
5. Include the header file :
   • xhw_types.h
   • xhw_memmap.h
   • xhw_ints.h
   • xgpio.h or the peripheral that you use.
6. APIs with a prefix x, are the CoX unified interface, which are compatible with a variety of MCUs.
7. APIs without the prefix x, are for special MCU features. The library also implement fully functions of the MCU peripheral.
8. Write your applications.

1.2 How to use GPIO shortpin(PA0) feature?

1.2.1 What is a GPIO shortpin?

A GPIO pin always contains info of a GPIO port(GPIO_PORTA_BASE), and a GPIO Pin(GPIO_PIN_0).

A GPIO shortpin in cox is a macro contained port, pin information in one body. PA0, A indicates GPIO_PortA_BASE, 0 indicates GPIO_PIN_0.

1.2.2 When to use the shortpin feature?

• When you just operate a pin in the port.
• When a driver device uses a GPIO pin.
• The more simple AFIO operation, such as xSPinTypeCAN(CAN0RX, PA4);
• ...

1.2.3 How to use the shortpin feature?

Use the shortpin to read/write:

• xGPIOSPinWrite(PA3, 0);
• ulPinState = xGPIOSPinRead(PA3);

Use the shortpin AFIO operation:

• xSPinTypeCAN(CAN0RX, PA4);
• xSPinTypeADC() ...

Use the shortpin in a device driver:

 #define SPI_FLASH_PIN_CS  PC2

 xGPIOSPinWrite(SPI_FLASH_PIN_CS, 0);

There is also APIs to get the Port, Pin:

• xSPintoPort(PA0); - result is GPIO_PIN_0
• xSPintoPin(PA0); - result is GPIO_PORTA_BASE
• xSPintoPortPin(PA0), in a struct - result like: GPIO_PORTA_BASE, GPIO_PIN_0,

1.3 How to use the CoX interrupt feature?

CoX unified defines the interruption of peripherals Compatible with a variety of MCUs using a callback function with an event ID.

Users should use the Event ID, not the interrupt flags in the MCU peripherals.

Users should also use the callback function instead of the interrupt Handler function defined in the vector table.

Step of Using the interrupt feature:

1. xSPIIntCallbackInit() Init the callback function.
2. xSPIIntEnable() to enable the interrupt.
3. xIntEnable() to enable the interrupt in the NVIC level.
4. Your code in the callback function will be called when an interrupt event coming.

1.4 How to Use the Peripheral?

1. First of all, you should set the system clock using XSysCtlClockSet().

2. If you use a peripheral such as SPI, you should enable the SPI clock and some GPIO clock before calling any SPI APIs.

 xSysCtlPeripheralEnable(xSYSCTL_PERIPH_SPI0);
 xSysCtlPeripheralEnable(xGPIOSPinToPeripheralId(FLASH_PIN_SPI_CLK));
 xSysCtlPeripheralEnable(xGPIOSPinToPeripheralId(FLASH_PIN_SPI_CS));
 xSysCtlPeripheralEnable(xGPIOSPinToPeripheralId(FLASH_PIN_SPI_MISO));
 xSysCtlPeripheralEnable(xGPIOSPinToPeripheralId(FLASH_PIN_SPI_MOSI));

3. Then you should config the SPI IO.

 xSPinTypeSPI(SPI2CLK, FLASH_PIN_SPI_CLK);
 xSPinTypeSPI(SPI2MISO, FLASH_PIN_SPI_MISO);
 xSPinTypeSPI(SPI2MOSI, FLASH_PIN_SPI_MOSI); 

4. You can enable and initialize the SPI.

 xSPIEnable(FLASH_PIN_SPI_PORT);
 xSPIConfigSet(FLASH_PIN_SPI_PORT, ulSpiClock, xSPI_MOTO_FORMAT_MODE_0 |
                                               xSPI_MODE_MASTER | 
                                               xSPI_MSB_FIRST |
                                               xSPI_DATA_WIDTH8); 

5. You can use SPI to communicate with a device.

1.5 Make your code be ported more easily based on CoX

Code based on CoX is convenient to port, but you can do more to make the code more portable.

For example: When using CoX SPI to write a SPI flash driver, we redefine the SPI base and shortpins. And then when need porting the code to other paltforms, We only need to change this defines.

 //
 // Define SPIx as a port connecting W25Xxx which can be configured
 //
 #define FLASH_PIN_SPI_CLK       PD1
 #define FLASH_PIN_SPI_MISO      PD2
 #define FLASH_PIN_SPI_MOSI      PD3
 #define FLASH_PIN_SPI_PORT      SPI2_BASE
 //
 // Configure GPIOC.0 as chip Select
 //
 #define FLASH_PIN_SPI_CS        PD0

1.6. Code Standard in CoX

1.6.1 Naming

• An API function name is always like: Moudle + Nouns + verbs, such as SPIIntEnable(), xGPIOSPinWrite() ....
• A variable name is always with a prefix:
  • unsigned long with a prefix ul, such as ulConfig;
  • unsigned char with a prefix uc, ucTemp;
  • A porter-type variables with prefix 'p', such as unsigned long *pulReadBuffer;
  • If the variable is global variable should plus an additional prefix "g_". such as unsigned long g_ulCalendar;
• source files name:
  • CoX source file is always have a prefix 'x', such as xuart.h, xuart.c
  • The header file contains peripheral register info, always called xhw_moudle.h, such as xhw_uart.h.

1.6.2 Doxygen

The presentment is using the doxygen standard.

2. How to Port CoX to other MCU platforms?

1. Download the blank template library.
2. Wirte the register info of the peripheral in the xhw_*.h.
3. Implement all the functions of the peripheral in the moudle.h/.c.
4. Port the APIs with the prefix 'x' based on the periperal functions you have implemented.
5. Test and write the doxygen documents.

If you encounter any problems in the porting period, please contact us.