# HYPLNK LLD Functions
[HYPLNK LLD Module API]

## Functions

hyplnkRet_e | Hyplnk_open (int portNum, Hyplnk_Handle *pHandle)
| Hyplnk_open creates/opens a HyperLink instance.
hyplnkRet_e | Hyplnk_close (Hyplnk_Handle *pHandle)
| Hyplnk_close Closes (frees) the driver handle.
hyplnkRet_e | Hyplnk_readRegs (Hyplnk_Handle handle, hyplnkLocation_e location, hyplnkRegisters_t *readRegs)
| Performs a configuration read.
hyplnkRet_e | Hyplnk_writeRegs (Hyplnk_Handle handle, hyplnkLocation_e location, hyplnkRegisters_t *writeRegs)
| Performs a configuration write.
hyplnkRet_e | Hyplnk_getWindow (Hyplnk_Handle handle, void **base, uint32_t *size)
| Hyplnk_getWindow returns the address and size of the local memory window.
uint32_t | Hyplnk_getVersion (void)
| Hyplnk_getVersion returns the HYPLNK LLD version information.
const char * | Hyplnk_getVersionStr (void)
| Hyplnk_getVersionStr returns the HYPLNK LLD version string.

## Function Documentation

hyplnkRet_e Hyplnk_close | ( | Hyplnk_Handle * | pHandle | ) |

Hyplnk_close Closes (frees) the driver handle.

The handle is released. The peripheral itself is not modified.

Precondition:
  pHandle != NULL
  *pHandle == valid handle

Return values:

  | hyplnkRet_e | status

Postcondition:
  *pHandle == NULL

Parameters:

  `[in]` | pHandle | The HYPLNK LLD instance indentifier

uint32_t Hyplnk_getVersion | ( | void |  | ) |

Hyplnk_getVersion returns the HYPLNK LLD version information.

This function is used to get the version information of the HYPLNK LLD in 0xAABBCCDD format. where Arch (AA); API Changes (BB); Major (CC); Minor (DD)

Return values:

  | 32-bit | version information

const char* Hyplnk_getVersionStr | ( | void |  | ) |

Hyplnk_getVersionStr returns the HYPLNK LLD version string.

This function is used to get the version string of the HYPLNK LLD.

Return values:

  | Version | string

hyplnkRet_e Hyplnk_getWindow | ( | Hyplnk_Handle | handle,
|  | void ** | base,
|  | uint32_t * | size |
| ) |  |  |

Hyplnk_getWindow returns the address and size of the local memory window.

Return values:

  | hyplnkRet_e | status

Parameters:

  `[in]` | handle | The HYPLNK LLD instance identifier
  `[out]` | base | The data base address
  `[out]` | size | Data window size [bytes]

hyplnkRet_e Hyplnk_open | ( | int | portNum,
|  | Hyplnk_Handle * | pHandle |
| ) |  |  |

Hyplnk_open creates/opens a HyperLink instance.

This function creates a handle. The peripheral itself is not modified. More than one handle to the same hyperlink peripheral can exist at the same time.

Precondition:
  pHandle != NULL
  *pHandle == NULL

Return values:

  | hyplnkRet_e | status

Postcondition:
  *pHandle == valid handle

Parameters:

  `[in]` | portNum | HyperLink port number (0,1,...)

Current KeyStone devices only have one HyperLink port (port 0). The port number allows forwards compatibility if future devices have multiple ports.

Parameters:

  `[out]` | pHandle | Resulting instance handle

hyplnkRet_e Hyplnk_readRegs | ( | Hyplnk_Handle | handle,
|  | hyplnkLocation_e | location,
|  | hyplnkRegisters_t * | readRegs |
| ) |  |  |

Performs a configuration read.

Reads one or more of the device registers

Each non-NULL register pointer in readRegs will be read and broken into its fields.

It is the users responsibility to ensure that no other tasks or cores will modify the registers while they are read, or betwen the time the registers are read and they are later written back.

When the table-at-once fields are used (hyplnkRegisters_s::RXPrivIDTbl hyplnkRegisters_s::RXSegTbl hyplnkRegisters_s::intCtrlTbl hyplnkRegisters_s::intPtrTbl), then this API will generate implicit register writes, so it should not be assumed that multiple simutaneous reads are safe.

Since the peripheral is shared across the device, and even between peripherals, it is not expected to be dynamically reprogramed (such as between thread or task switches). It should only be reprogrammed at startup or when changing applications. Therefore, there is a single-entry API instead of a set of inlines since it is not time-critical code.

Return values:

  | hyplnkRet_e | status

Parameters:

  `[in]` | handle | The HYPLNK LLD instance identifier
  `[in]` | location | Local or remote peripheral
  `[in,out]` | readRegs | List of registers to read

hyplnkRet_e Hyplnk_writeRegs | ( | Hyplnk_Handle | handle,
|  | hyplnkLocation_e | location,
|  | hyplnkRegisters_t * | writeRegs |
| ) |  |  |

Performs a configuration write.

Writes one or more of the device registers

It is the users responsibility to ensure that no other tasks or cores will modify the registers while they are read, or betwen the time the registers are read and they are later written back.

The user will typically use Hyplnk_readRegs to read the current values in the registers, modify them in the local copies, then write back using Hyplnk_writeRegs.

It is guaranteed that all registers can be written together. The actual ordering will, for example, write index registers before the associated value registers

On exit, the actual written values are returned in each register's reg->raw.

Since the peripheral is shared across the device, and even between peripherals, it is not expected to be dynamically reprogramed (such as between thread or task switches). It should only be reprogrammed at startup or when changing applications. Therefore, there is a single-entry API instead of a set of inlines since it is not time-critical code.

Return values:

  | hyplnkRet_e | status

Parameters:

  `[in]` | handle | The HYPLNK LLD instance identifier
  `[in]` | location | Local or remote peripheral
  `[in]` | writeRegs | List of registers to write

Copyright 2012, Texas Instruments Incorporated