\doxysection{Osmocom primitives}
\label{group__prim}\index{Osmocom primitives@{Osmocom primitives}}


Osmocom Primitives are a method to express inter-\/layer primitives as used often in ITU/\+ETSI/3\+GPP specifications in a generic way.  


\doxysubsection*{Files}
\begin{DoxyCompactItemize}
\item 
file \textbf{ prim.\+h}
\item 
file \textbf{ prim.\+c}
\end{DoxyCompactItemize}
\doxysubsection*{Data Structures}
\begin{DoxyCompactItemize}
\item 
struct \textbf{ osmo\+\_\+prim\+\_\+hdr}
\begin{DoxyCompactList}\small\item\em Osmocom primitive header. \end{DoxyCompactList}\item 
struct \textbf{ osmo\+\_\+prim\+\_\+event\+\_\+map}
\begin{DoxyCompactList}\small\item\em single entry in a SAP/\+PRIM/\+OP -\/$>$ EVENT map \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Macros}
\begin{DoxyCompactItemize}
\item 
\#define \textbf{ OSMO\+\_\+\+PRIM}(prim,  op)~((prim $<$$<$ 8) $\vert$ (op \& 0x\+FF))
\item 
\#define \textbf{ OSMO\+\_\+\+PRIM\+\_\+\+HDR}(oph)~\textbf{ OSMO\+\_\+\+PRIM}((oph)-\/$>$primitive, (oph)-\/$>$operation)
\item 
\#define \textbf{ \+\_\+\+SAP\+\_\+\+GSM\+\_\+\+SHIFT}~24
\item 
\#define \textbf{ \+\_\+\+SAP\+\_\+\+GSM\+\_\+\+BASE}~(0x01 $<$$<$ \textbf{ \+\_\+\+SAP\+\_\+\+GSM\+\_\+\+SHIFT})
\item 
\#define \textbf{ \+\_\+\+SAP\+\_\+\+TETRA\+\_\+\+BASE}~(0x02 $<$$<$ \textbf{ \+\_\+\+SAP\+\_\+\+GSM\+\_\+\+SHIFT})
\item 
\#define \textbf{ \+\_\+\+SAP\+\_\+\+SS7\+\_\+\+BASE}~(0x03 $<$$<$ \textbf{ \+\_\+\+SAP\+\_\+\+GSM\+\_\+\+SHIFT})
\item 
\#define \textbf{ OSMO\+\_\+\+NO\+\_\+\+EVENT}~0x\+FFFFFFFF
\begin{DoxyCompactList}\small\item\em magic value to be used as final record of \doxyref{osmo\+\_\+prim\+\_\+event\+\_\+map}{p.}{structosmo__prim__event__map} \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Typedefs}
\begin{DoxyCompactItemize}
\item 
typedef int($\ast$ \textbf{ osmo\+\_\+prim\+\_\+cb}) (struct \textbf{ osmo\+\_\+prim\+\_\+hdr} $\ast$oph, void $\ast$ctx)
\begin{DoxyCompactList}\small\item\em primitive handler callback type \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Enumerations}
\begin{DoxyCompactItemize}
\item 
enum \textbf{ osmo\+\_\+prim\+\_\+operation} \{ \newline
\textbf{ PRIM\+\_\+\+OP\+\_\+\+REQUEST}
, \newline
\textbf{ PRIM\+\_\+\+OP\+\_\+\+RESPONSE}
, \newline
\textbf{ PRIM\+\_\+\+OP\+\_\+\+INDICATION}
, \newline
\textbf{ PRIM\+\_\+\+OP\+\_\+\+CONFIRM}
 \}
\begin{DoxyCompactList}\small\item\em primitive operation \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Functions}
\begin{DoxyCompactItemize}
\item 
static const char $\ast$ \textbf{ osmo\+\_\+prim\+\_\+operation\+\_\+name} (enum \textbf{ osmo\+\_\+prim\+\_\+operation} val)
\begin{DoxyCompactList}\small\item\em The upper 8 byte of the technology, the lower 24 bits for the SAP. \end{DoxyCompactList}\item 
static void \textbf{ osmo\+\_\+prim\+\_\+init} (struct \textbf{ osmo\+\_\+prim\+\_\+hdr} $\ast$oph, unsigned int sap, unsigned int primitive, enum \textbf{ osmo\+\_\+prim\+\_\+operation} operation, struct \textbf{ msgb} $\ast$\textbf{ msg})
\begin{DoxyCompactList}\small\item\em Convenience function to initialize a primitive header. \end{DoxyCompactList}\item 
uint32\+\_\+t \textbf{ osmo\+\_\+event\+\_\+for\+\_\+prim} (const struct \textbf{ osmo\+\_\+prim\+\_\+hdr} $\ast$oph, const struct \textbf{ osmo\+\_\+prim\+\_\+event\+\_\+map} $\ast$maps)
\begin{DoxyCompactList}\small\item\em resolve the (fsm) event for a given primitive using a map \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Variables}
\begin{DoxyCompactItemize}
\item 
const struct \textbf{ value\+\_\+string} \textbf{ osmo\+\_\+prim\+\_\+op\+\_\+names} [$\,$]
\begin{DoxyCompactList}\small\item\em human-\/readable string mapping for \doxyref{osmo\+\_\+prim\+\_\+operation}{p.}{group__prim_ga5bd3196233677c8e9ab66b6fb97060d3} \end{DoxyCompactList}\item 
const struct \textbf{ value\+\_\+string} \textbf{ osmo\+\_\+prim\+\_\+op\+\_\+names} [5]
\begin{DoxyCompactList}\small\item\em human-\/readable string mapping for \doxyref{osmo\+\_\+prim\+\_\+operation}{p.}{group__prim_ga5bd3196233677c8e9ab66b6fb97060d3} \end{DoxyCompactList}\end{DoxyCompactItemize}


\doxysubsection{Detailed Description}
Osmocom Primitives are a method to express inter-\/layer primitives as used often in ITU/\+ETSI/3\+GPP specifications in a generic way. 

(C) 2015-\/2017 by Harald Welte {\texttt{ laforge@gnumonks.\+org}} All Rights Reserved

They are based on \doxyref{Message buffers}{p.}{group__msgb} and encapsulate any (optional) user payload data with a primitive header. The header contains information on
\begin{DoxyItemize}
\item which SAP this primitive is used on
\item what is the name of the primitive
\item is it REQUEST, RESPONSE, INDICATION or CONFIRMATION
\end{DoxyItemize}

For more information on the inter-\/layer primitives concept, see ITU-\/T X.\+21@ as found at {\texttt{ https\+://www.\+itu.\+int/rec/\+T-\/\+REC-\/\+X.\+212-\/199511-\/\+I/en}}

SPDX-\/\+License-\/\+Identifier\+: GPL-\/2.\+0+ 

\doxysubsection{Macro Definition Documentation}
\mbox{\label{group__prim_gafede4906436eeaac53464216f112a2d9}} 
\index{Osmocom primitives@{Osmocom primitives}!\_SAP\_GSM\_BASE@{\_SAP\_GSM\_BASE}}
\index{\_SAP\_GSM\_BASE@{\_SAP\_GSM\_BASE}!Osmocom primitives@{Osmocom primitives}}
\doxysubsubsection{\_SAP\_GSM\_BASE}
{\footnotesize\ttfamily \#define \+\_\+\+SAP\+\_\+\+GSM\+\_\+\+BASE~(0x01 $<$$<$ \textbf{ \+\_\+\+SAP\+\_\+\+GSM\+\_\+\+SHIFT})}

\mbox{\label{group__prim_gaa9cc671e11971c5cbd2e8fbe9c5de332}} 
\index{Osmocom primitives@{Osmocom primitives}!\_SAP\_GSM\_SHIFT@{\_SAP\_GSM\_SHIFT}}
\index{\_SAP\_GSM\_SHIFT@{\_SAP\_GSM\_SHIFT}!Osmocom primitives@{Osmocom primitives}}
\doxysubsubsection{\_SAP\_GSM\_SHIFT}
{\footnotesize\ttfamily \#define \+\_\+\+SAP\+\_\+\+GSM\+\_\+\+SHIFT~24}

\mbox{\label{group__prim_ga7f7c1f3030da0d2aa57f4c69a99d06e9}} 
\index{Osmocom primitives@{Osmocom primitives}!\_SAP\_SS7\_BASE@{\_SAP\_SS7\_BASE}}
\index{\_SAP\_SS7\_BASE@{\_SAP\_SS7\_BASE}!Osmocom primitives@{Osmocom primitives}}
\doxysubsubsection{\_SAP\_SS7\_BASE}
{\footnotesize\ttfamily \#define \+\_\+\+SAP\+\_\+\+SS7\+\_\+\+BASE~(0x03 $<$$<$ \textbf{ \+\_\+\+SAP\+\_\+\+GSM\+\_\+\+SHIFT})}

\mbox{\label{group__prim_ga66ac978ed015c4111d846c5e1dee1449}} 
\index{Osmocom primitives@{Osmocom primitives}!\_SAP\_TETRA\_BASE@{\_SAP\_TETRA\_BASE}}
\index{\_SAP\_TETRA\_BASE@{\_SAP\_TETRA\_BASE}!Osmocom primitives@{Osmocom primitives}}
\doxysubsubsection{\_SAP\_TETRA\_BASE}
{\footnotesize\ttfamily \#define \+\_\+\+SAP\+\_\+\+TETRA\+\_\+\+BASE~(0x02 $<$$<$ \textbf{ \+\_\+\+SAP\+\_\+\+GSM\+\_\+\+SHIFT})}

\mbox{\label{group__prim_gaada260e79492bf89c208db9184174459}} 
\index{Osmocom primitives@{Osmocom primitives}!OSMO\_NO\_EVENT@{OSMO\_NO\_EVENT}}
\index{OSMO\_NO\_EVENT@{OSMO\_NO\_EVENT}!Osmocom primitives@{Osmocom primitives}}
\doxysubsubsection{OSMO\_NO\_EVENT}
{\footnotesize\ttfamily \#define OSMO\+\_\+\+NO\+\_\+\+EVENT~0x\+FFFFFFFF}



magic value to be used as final record of \doxyref{osmo\+\_\+prim\+\_\+event\+\_\+map}{p.}{structosmo__prim__event__map} 

\mbox{\label{group__prim_ga173c203440160e63e5c588870638607a}} 
\index{Osmocom primitives@{Osmocom primitives}!OSMO\_PRIM@{OSMO\_PRIM}}
\index{OSMO\_PRIM@{OSMO\_PRIM}!Osmocom primitives@{Osmocom primitives}}
\doxysubsubsection{OSMO\_PRIM}
{\footnotesize\ttfamily \#define OSMO\+\_\+\+PRIM(\begin{DoxyParamCaption}\item[{}]{prim,  }\item[{}]{op }\end{DoxyParamCaption})~((prim $<$$<$ 8) $\vert$ (op \& 0x\+FF))}

\mbox{\label{group__prim_ga43873bb5609b3d8c72a740c095264b3b}} 
\index{Osmocom primitives@{Osmocom primitives}!OSMO\_PRIM\_HDR@{OSMO\_PRIM\_HDR}}
\index{OSMO\_PRIM\_HDR@{OSMO\_PRIM\_HDR}!Osmocom primitives@{Osmocom primitives}}
\doxysubsubsection{OSMO\_PRIM\_HDR}
{\footnotesize\ttfamily \#define OSMO\+\_\+\+PRIM\+\_\+\+HDR(\begin{DoxyParamCaption}\item[{}]{oph }\end{DoxyParamCaption})~\textbf{ OSMO\+\_\+\+PRIM}((oph)-\/$>$primitive, (oph)-\/$>$operation)}



\doxysubsection{Typedef Documentation}
\mbox{\label{group__prim_gab56d32c84797be881ccafdebe4b78b2a}} 
\index{Osmocom primitives@{Osmocom primitives}!osmo\_prim\_cb@{osmo\_prim\_cb}}
\index{osmo\_prim\_cb@{osmo\_prim\_cb}!Osmocom primitives@{Osmocom primitives}}
\doxysubsubsection{osmo\_prim\_cb}
{\footnotesize\ttfamily typedef int($\ast$ osmo\+\_\+prim\+\_\+cb) (struct \textbf{ osmo\+\_\+prim\+\_\+hdr} $\ast$oph, void $\ast$ctx)}



primitive handler callback type 



\doxysubsection{Enumeration Type Documentation}
\mbox{\label{group__prim_ga5bd3196233677c8e9ab66b6fb97060d3}} 
\index{Osmocom primitives@{Osmocom primitives}!osmo\_prim\_operation@{osmo\_prim\_operation}}
\index{osmo\_prim\_operation@{osmo\_prim\_operation}!Osmocom primitives@{Osmocom primitives}}
\doxysubsubsection{osmo\_prim\_operation}
{\footnotesize\ttfamily enum \textbf{ osmo\+\_\+prim\+\_\+operation}}



primitive operation 

\begin{DoxyEnumFields}{Enumerator}
\raisebox{\heightof{T}}[0pt][0pt]{\index{PRIM\_OP\_REQUEST@{PRIM\_OP\_REQUEST}!Osmocom primitives@{Osmocom primitives}}\index{Osmocom primitives@{Osmocom primitives}!PRIM\_OP\_REQUEST@{PRIM\_OP\_REQUEST}}}\mbox{\label{group__prim_gga5bd3196233677c8e9ab66b6fb97060d3aef3a9ebe139f54ca2c1dae8b65c6880e}} 
PRIM\+\_\+\+OP\+\_\+\+REQUEST&request \\
\hline

\raisebox{\heightof{T}}[0pt][0pt]{\index{PRIM\_OP\_RESPONSE@{PRIM\_OP\_RESPONSE}!Osmocom primitives@{Osmocom primitives}}\index{Osmocom primitives@{Osmocom primitives}!PRIM\_OP\_RESPONSE@{PRIM\_OP\_RESPONSE}}}\mbox{\label{group__prim_gga5bd3196233677c8e9ab66b6fb97060d3af62503bb7df5fde38f9359b591028dc1}} 
PRIM\+\_\+\+OP\+\_\+\+RESPONSE&response \\
\hline

\raisebox{\heightof{T}}[0pt][0pt]{\index{PRIM\_OP\_INDICATION@{PRIM\_OP\_INDICATION}!Osmocom primitives@{Osmocom primitives}}\index{Osmocom primitives@{Osmocom primitives}!PRIM\_OP\_INDICATION@{PRIM\_OP\_INDICATION}}}\mbox{\label{group__prim_gga5bd3196233677c8e9ab66b6fb97060d3a6987bf8560df352ada9979b4457f9f0d}} 
PRIM\+\_\+\+OP\+\_\+\+INDICATION&indication \\
\hline

\raisebox{\heightof{T}}[0pt][0pt]{\index{PRIM\_OP\_CONFIRM@{PRIM\_OP\_CONFIRM}!Osmocom primitives@{Osmocom primitives}}\index{Osmocom primitives@{Osmocom primitives}!PRIM\_OP\_CONFIRM@{PRIM\_OP\_CONFIRM}}}\mbox{\label{group__prim_gga5bd3196233677c8e9ab66b6fb97060d3aee86a39134232ad0417a13ef1f8e53bf}} 
PRIM\+\_\+\+OP\+\_\+\+CONFIRM&confirm \\
\hline

\end{DoxyEnumFields}


\doxysubsection{Function Documentation}
\mbox{\label{group__prim_ga65cffc8b84a2c3d2f200560096810695}} 
\index{Osmocom primitives@{Osmocom primitives}!osmo\_event\_for\_prim@{osmo\_event\_for\_prim}}
\index{osmo\_event\_for\_prim@{osmo\_event\_for\_prim}!Osmocom primitives@{Osmocom primitives}}
\doxysubsubsection{osmo\_event\_for\_prim()}
{\footnotesize\ttfamily uint32\+\_\+t osmo\+\_\+event\+\_\+for\+\_\+prim (\begin{DoxyParamCaption}\item[{const struct \textbf{ osmo\+\_\+prim\+\_\+hdr} $\ast$}]{oph,  }\item[{const struct \textbf{ osmo\+\_\+prim\+\_\+event\+\_\+map} $\ast$}]{maps }\end{DoxyParamCaption})}



resolve the (fsm) event for a given primitive using a map 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in}}  & {\em oph} & primitive header used as key for match \\
\hline
\mbox{\texttt{ in}}  & {\em maps} & list of mappings from primitive to event \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
event determined by map; \doxyref{OSMO\+\_\+\+NO\+\_\+\+EVENT}{p.}{group__prim_gaada260e79492bf89c208db9184174459} if no match 
\end{DoxyReturn}


References \textbf{ osmo\+\_\+prim\+\_\+event\+\_\+map\+::event}, \textbf{ osmo\+\_\+prim\+\_\+hdr\+::operation}, \textbf{ osmo\+\_\+prim\+\_\+event\+\_\+map\+::operation}, \textbf{ OSMO\+\_\+\+NO\+\_\+\+EVENT}, \textbf{ osmo\+\_\+prim\+\_\+hdr\+::primitive}, \textbf{ osmo\+\_\+prim\+\_\+event\+\_\+map\+::primitive}, \textbf{ osmo\+\_\+prim\+\_\+hdr\+::sap}, and \textbf{ osmo\+\_\+prim\+\_\+event\+\_\+map\+::sap}.

\mbox{\label{group__prim_gaf826713c118d129aff1a700a742552c4}} 
\index{Osmocom primitives@{Osmocom primitives}!osmo\_prim\_init@{osmo\_prim\_init}}
\index{osmo\_prim\_init@{osmo\_prim\_init}!Osmocom primitives@{Osmocom primitives}}
\doxysubsubsection{osmo\_prim\_init()}
{\footnotesize\ttfamily static void osmo\+\_\+prim\+\_\+init (\begin{DoxyParamCaption}\item[{struct \textbf{ osmo\+\_\+prim\+\_\+hdr} $\ast$}]{oph,  }\item[{unsigned int}]{sap,  }\item[{unsigned int}]{primitive,  }\item[{enum \textbf{ osmo\+\_\+prim\+\_\+operation}}]{operation,  }\item[{struct \textbf{ msgb} $\ast$}]{msg }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [static]}}



Convenience function to initialize a primitive header. 


\begin{DoxyParams}[1]{Parameters}
\mbox{\texttt{ in,out}}  & {\em oph} & primitive header \\
\hline
\mbox{\texttt{ in}}  & {\em sap} & Service Access Point \\
\hline
\mbox{\texttt{ in}}  & {\em primitive} & Primitive Number \\
\hline
\mbox{\texttt{ in}}  & {\em operation} & Primitive Operation (REQ/\+RESP/\+IND/\+CONF) \\
\hline
\mbox{\texttt{ in}}  & {\em msg} & Message \\
\hline
\end{DoxyParams}


References \textbf{ msg}, \textbf{ osmo\+\_\+prim\+\_\+hdr\+::msg}, \textbf{ osmo\+\_\+prim\+\_\+hdr\+::operation}, \textbf{ osmo\+\_\+prim\+\_\+hdr\+::primitive}, and \textbf{ osmo\+\_\+prim\+\_\+hdr\+::sap}.

\mbox{\label{group__prim_ga771deac5835b0ce81dc8d7390f8e00f2}} 
\index{Osmocom primitives@{Osmocom primitives}!osmo\_prim\_operation\_name@{osmo\_prim\_operation\_name}}
\index{osmo\_prim\_operation\_name@{osmo\_prim\_operation\_name}!Osmocom primitives@{Osmocom primitives}}
\doxysubsubsection{osmo\_prim\_operation\_name()}
{\footnotesize\ttfamily static const char $\ast$ osmo\+\_\+prim\+\_\+operation\+\_\+name (\begin{DoxyParamCaption}\item[{enum \textbf{ osmo\+\_\+prim\+\_\+operation}}]{val }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [static]}}



The upper 8 byte of the technology, the lower 24 bits for the SAP. 



References \textbf{ get\+\_\+value\+\_\+string()}, and \textbf{ osmo\+\_\+prim\+\_\+op\+\_\+names}.



\doxysubsection{Variable Documentation}
\mbox{\label{group__prim_ga886b7582fd2947d0582cd8c9acd30cc9}} 
\index{Osmocom primitives@{Osmocom primitives}!osmo\_prim\_op\_names@{osmo\_prim\_op\_names}}
\index{osmo\_prim\_op\_names@{osmo\_prim\_op\_names}!Osmocom primitives@{Osmocom primitives}}
\doxysubsubsection{osmo\_prim\_op\_names\hspace{0.1cm}{\footnotesize\ttfamily [1/2]}}
{\footnotesize\ttfamily const struct \textbf{ value\+\_\+string} osmo\+\_\+prim\+\_\+op\+\_\+names[5]}

{\bfseries Initial value\+:}
\begin{DoxyCode}{0}
\DoxyCodeLine{= \{}
\DoxyCodeLine{        \{ PRIM\_OP\_REQUEST,                       \textcolor{stringliteral}{"{}request"{}} \},}
\DoxyCodeLine{        \{ PRIM\_OP\_RESPONSE,                     \textcolor{stringliteral}{"{}response"{}} \},}
\DoxyCodeLine{        \{ PRIM\_OP\_INDICATION,                 \textcolor{stringliteral}{"{}indication"{}} \},}
\DoxyCodeLine{        \{ PRIM\_OP\_CONFIRM,                       \textcolor{stringliteral}{"{}confirm"{}} \},}
\DoxyCodeLine{        \{ 0, NULL \}}
\DoxyCodeLine{\}}

\end{DoxyCode}


human-\/readable string mapping for \doxyref{osmo\+\_\+prim\+\_\+operation}{p.}{group__prim_ga5bd3196233677c8e9ab66b6fb97060d3} 



Referenced by \textbf{ osmo\+\_\+prim\+\_\+operation\+\_\+name()}.

\mbox{\label{group__prim_gae79f3e17450603fb5f3c5444fb845f0d}} 
\index{Osmocom primitives@{Osmocom primitives}!osmo\_prim\_op\_names@{osmo\_prim\_op\_names}}
\index{osmo\_prim\_op\_names@{osmo\_prim\_op\_names}!Osmocom primitives@{Osmocom primitives}}
\doxysubsubsection{osmo\_prim\_op\_names\hspace{0.1cm}{\footnotesize\ttfamily [2/2]}}
{\footnotesize\ttfamily const struct \textbf{ value\+\_\+string} osmo\+\_\+prim\+\_\+op\+\_\+names[$\,$]\hspace{0.3cm}{\ttfamily [extern]}}



human-\/readable string mapping for \doxyref{osmo\+\_\+prim\+\_\+operation}{p.}{group__prim_ga5bd3196233677c8e9ab66b6fb97060d3} 



Referenced by \textbf{ osmo\+\_\+prim\+\_\+operation\+\_\+name()}.

